1 260
szerkesztés
Módosítások
heavy restructuring
{{STOP|This document is written for module version 4.0-x ('''development branch'''). Please consult the [[#Change log]] for the revisions of this document for the previous releases.}}
== Installation and bootstrapping ===== Installing the module ===
# Download module source for your Drupal version from the [http://drupal.org/project/shib_auth project page].
# Uncompress archive to the <code>modules/</code> directory
# Enable module at '''<code>Administer -> Site building -> Modules</code>'''
==== Compatibility ====
Module is being developed for Drupal 6.x. We have stopped backporting new features to the 5.x branch and Drupal 7 is not yet supported as long as it isn't the stable branch. If you want to contribute to development or porting, please contact '''aai _AT_ niif _DOT_ hu'''!
}}
The upgrade script creates a new makes slight changes to the database table called <code>shib_authmap</code>, and place the usernames that were registered by the module into it. You only need to run this script once, however running it several times does no harm to your installation apart from showing some SQL errors. :: '''Note:''' {{NOTE_EN|although the upgrade script was designed to be robust, please '''back up your database''' before upgrading.}} == Configuration = Get it running ======= Configuring Shibboleth ====You should be familiar with protecting resources with Shibboleth before using this module. (See [https://spaces.internet2.edu/display/SHIB2/NativeSPProtectContent Shibboleth Wiki]for more extensive information) Please check that Shibboleth authentication is working for the location of your Drupal installation and all the necessary attributes are exported to the headers. You can enable [[Drupal Shibboleth module#DEBUG mode | DEBUG mode]] to dump the whole '''$_SERVER''' array. If you can see Shibboleth attributes there, you're fine.
In Shibboleth there are two modes for protecting resources:
* '''Lazy Sessions''': session is only initiated if an application redirects user to the SessionInitiator URL. In this module, it is done by clicking the ''"Login with Shibboleth"'' link. Anonymous access is possible as well as using other authentication methods. This is what you want to use for a CMS that contains ''public information''.
:: <small>Detailed description of [[Lazy Session|lazy sessions]] in Hungarian.</small>
* '''"Strict" Sessions''' (normal sessions): users can only access Drupal content if they have a valid Shibboleth session. In this case, no anonymous access can be granted (not even read-only) and you can not use any auxiliary authentication methods.Most of the advanced features don't work with strict sessions. You should not use this unless you want to protect all the information in the CMS from viewing. {{STOPNOTE_EN|If you decide to use lazy after enabling "strict" sessions and , you donwon't want your users to be able to log in login with a password, admin user. [[#Disallowing password changeAdministering Drupal with strict sessions|you have to disable changing passwordsRead on further]]how to give your own user administrator rights.}} ===== Example Shibboleth configuration =====
{{NOTE_EN|this example uses lazy sessions. Configuration for Shibboleth 1.3 is quite similar.}}
Shibboleth 1.3 always uses headers, therefore the <code>ShibUseHeaders</code> directive is invalid with Shibboleth 1.3.}}
==== DEBUG mode ====
If you enable DEBUG mode on the module configuration interface, you can dump the whole '''$_SERVER''' array. This shows you all the available attributes and helps you diagnosing possible Shibboleth attribute problems.
:: <small>Keep in mind that some users might have a specific attribute while others don't.</small>
===== Debug path prefix =====
Leave it empty, if you want to display debug information on every page. Enter the string ''<code>user/</code>'' for displaying DEBUG messages only on paths below <code>user/*</code>
Adding a prefix is useful, if you want to enable debugging on an online drupal installation without littering all of the pages with the debugging information. You can set it to a non-existent node as well, in this case, the information will be displayed over the built-in 404 page.
==== Setting Shibboleth parameters for the module ========= Handler settings =====
If you are using lazy sessions, you have to define the Shibboleth SessionInitiator to which the user should be directed when she clicks on "Login with Shibboleth". SessionInitiator URL is constituted of the following:
* protocol scheme (<code>http://</code> or <code>https://</code>)
* '''/Login''' for ''WAYF location''
===== Attribute settings =====
Specify here the '''$_SERVER''' headers to look up the user's username and e-mail address. Please check '''DEBUG''' mode to look for the available headers. If you can not find the desired attribute, then something is wrong with your IdP-SP attribute release flow.
Both fields can have the same value, if you wish.
== Understanding features ===== Automatic user creation ===Drupal CMS requires all users to be in its internal SQL database. If the module detects that no user exists in the database with the received Shibboleth user identifier, it creates a new (Drupal) user. Drupal needs 3 pieces of information to create a new user:* username* e-mail address* password The module by default uses the username and e-mail address taken from the <code>$_SERVER</code> headers, see [[#Attribute settings]] right above. On new user creation a random password is generated. This can be overwritten by the user unless you [[#Disallowing password change|disallow it]] by the userprotect module.{{NOTE_EN|if the user overwrites the password, she can log in with her username and the new password. ==== Using custom values =====
You may want to let your users to define their own Drupal usernames and e-mail addresses other than what was received from the IdP. If either ''User-defined usernames'' or ''User-defined e-mail addresses'' option is set, new users are presented a form to enter data at the first logon.
{{INFO_EN|
* The module ensures that neither values are in use by existing users.
* If you enable and later disable the options, the two behave a bit differently. On subsequent logons:
** the user-defined username is '''preserved'''
** e-mail address gets '''rewritten''' (or the user gets a fatal error if the IdP does not provide the data)
* User-defined e-mail addresses are not verified, only well-formedness is checked
}}
==== Working with federated identifiers ====
If you enable the option ''User-defined usernames'' in the module configuration, every new user is presented a form to specify a Drupal username. This way you can work with opaque (federated) identifiers such as <code>eduPersonTargetedId</code>, as long as it appears in the $_SERVER variable holding the username. The only limitation is that the federated identifier cannot be longer than 255 characters, however it can contain characters otherwise not allowed in Drupal account names (such as exclamation mark, etc).
==== Disallowing password change ====
If you don't want to let your users to change passwords and log in with it, you may want to disallow password change.
# Install Drupal [http://drupal.org/project/userprotect User Protect module]
# At Administer -> User management -> User Protect -> Protected roles tab check '''password''' for the ''authenticated user'' role.
# At Administer -> Permissions -> userprotect module: uncheck '''change own password''' for ''authenticated user''
# Log in with a normal account, go to "My account" -> Edit. You shouldn't see the possibility for changing password; except for the case when the user has user administrator rights.
==== Administering Drupal with strict sessions ====
If you use strict sessions, you can not log in with a password. You need to grant your own user administrator rights to administer the CMS.
# Enable Shibboleth protection
# Login with your own user credentials, so that your Drupal user profile is created
# Disable Shibboleth protection
# Login as 'admin', grant your own user 'Administrator' rights.
# Enable Shibboleth protection
# Login with your own credentials, you should have 'Administrator' rights now.
=== Logging out ===
==== Session expiry ====
Enable the option "''Destroy Drupal session when the Shibboleth session expires''", if you want to force logout the users without a valid Shibboleth session. (This only applies to lazy sessions, otherwise it is the webserver what ensures that you are always having have a Shibboleth valid session.)
{{INFO_EN|;Keep in mind if you leave this option off:
* '''$_SERVER''' header name: name of the Shibboleth-derived attribute
* '''Value regexp''': regexp applied to (all) the value(s) of the Shibboleth-derived attribute
* '''Role(s)''': checklist of roles to be assigned for to the matching users
{{NOTE_EN|Although although dynamic roles are '''NOT''' displayed on the user page, the permissions assigned to the role are in effect for the user. <br><small>This is a feature, not a bug</small>}}
Additional roles can be assigned statically to the user (as an individual) by the administrator as normally. Every logged in user gets the role <code>Authenticated user</code> automatically.
=== Account linking ===
# Login to Drupal (with username/password)
# Go to <code>My account -> Edit</code>
* On a new user logon, the one cannot choose the Drupal username of another user (when ''user-defined usernames'' is active). For account linking, the user must be already logged in.
}}
{{UNCERTAINATTENTION_EN|* Account linking is disabled when the user is logged in by the module. This might change in the future. * Dynamic roles are roles assigned to based on server variables, not users. These may well be different on username/password logon and Shibboleth logon.
}}
== Change log ==
