„DrupalShibbolethReadmeDev” változatai közötti eltérés

Innen: KIFÜ Wiki
a (Automatic user creation)
(+ User consent)
209. sor: 209. sor:
 
  </LogoutInitiator>
 
  </LogoutInitiator>
 
</source>
 
</source>
 +
 +
=== User consent ===
 +
In certain scenarios you are only allowed to store personal data if the user accepted some kind of legal agreement such as the Terms of Use or the Privacy Policy.
 +
 +
When a new user arrives, she gets a screen with a link to the legal document and a checkbox. This page also contains the user's name and the e-mail address. Personal data required for login are stored only if the user accepts the agreement. If it's allowed by the administrator, the user might set [[#Using_custom_values | custom values]] for those attributes.
 +
 +
If the document changes, the administrator might increment the version. This case all users are forced to accept the new version of the agreement before logging in.
 +
{{NOTE_EN|Version matching is an exact match, so the user must accept exactly the same version what was specified by the administrator}}
 +
==== Personal data handled by the module ====
 +
* username
 +
* user's e-mail address
 +
* user's targeted identifier(s) (what is sent by the IdP, if different from username), along with a mapping to the Drupal username
 +
* Identity Provider(s) that identified the user
 +
* random password (this might not be considered personal data)
 +
* time of the registration
  
 
== Change log ==
 
== Change log ==

A lap 2009. szeptember 15., 13:09-kori változata

Drupal shib_auth module enables Shibboleth authentication for Drupal CMS.


Installation and bootstrapping

Installing the module

  1. Download module source for your Drupal version from the project page.
  2. Uncompress archive to the modules/ directory
  3. Enable module at Administer -> Site building -> Modules

Compatibility

The module is supported for Drupal 6.x. No new features and patches (excluding security fixes) are backported to 5.x. Drupal 7 support will be added after it becomes an official stable version. If you want to contribute to development or porting, please contact aai _AT_ niif _DOT_ hu!

Both Shibboleth 1.3 and Shibboleth 2.x are supported, although some features will require Shibboleth 2.x.

Upgrading the module

If you upgrade from 3.x (or previous versions) to 4.x, you must update the database. After overwriting the files in the modules/ directory, open up YOUR_DRUPAL_INSTALLATION/update.php in your browser and run update for the shib_auth module. This is required to let your user info persist.

The upgrade script makes slight changes to the database. 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: although the upgrade script was designed to be robust, please back up your database before upgrading.

Get it running

Configuring Shibboleth

You should be familiar with protecting resources with Shibboleth before using this module. (See Shibboleth Wiki for comprehensive 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 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.
Detailed description of lazy sessions in Hungarian.
  • "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.
Note: after enabling "strict" sessions, you won't be able to login with admin user. Read on further how to give your own user administrator rights.
Example Shibboleth configuration
Note: this example uses lazy sessions. Configuration for Shibboleth 1.3 is quite similar.

/etc/shibboleth/shibboleth2.xml snippet:

<RequestMapper type="Native">
  <RequestMap applicationId="default">
    <Host name="your.host.name">
      <Path name="location_of">
        <Path name="your_Drupal">
          <Path name="installation" authType="shibboleth" requireSession="false" />
        </Path>
      </Path>
    </Host>
  </RequestMap>
</RequestMapper>


Apache config file snippet (ie. /etc/apache2/sites-enabled/your.host.name, or you can even use .htaccess without the <Location> tags):

<Location /location_of/your_Drupal/installation>
  AuthType Shibboleth
  ShibRequireSession Off
  # the following single line is only valid for Shib2
  ShibUseHeaders On
  require shibboleth
</Location>


You MUST use ShibUseHeaders On if you use Shibboleth2 with mod_rewrite.

mod_rewrite prefixes CGI environment variables with REDIRECT_, so you have to instruct Shibboleth2 to use headers instead.

Shibboleth 1.3 always uses headers, therefore the ShibUseHeaders 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.

Keep in mind that some users might have a specific attribute while others don't.
Debug path prefix

Leave it empty, if you want to display debug information on every page. Enter the string user/ (mind the trailing slash!) for displaying DEBUG messages only on paths below user/*

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". The SessionInitiator can be called on a special URL which depends on your Shibboleth configuration.

If your /etc/shibboleth/shibboleth2.xml is something like this:

<Sessions lifetime="28800" timeout="3600" checkAddress="false"
          handlerURL="/Shibboleth.sso" handlerSSL="false"
          exportLocation="http://localhost/Shibboleth.sso/GetAssertion"
          idpHistory="false" idpHistoryDays="7">
  <SessionInitiator type="Chaining" Location="/Login" isDefault="true" id="Intranet" 
                    relayState="cookie" entityID="https://idp.example.org/shibboleth">
    <SessionInitiator type="SAML2" defaultACSIndex="1" template="bindingTemplate.html"/>
    <SessionInitiator type="Shib1" defaultACSIndex="5"/>
  </SessionInitiator>
  <!-- other things -->
  <LogoutInitiator type="Chaining" Location="/Logout" relayState="cookie">
    <LogoutInitiator type="SAML2" template="bindingTemplate.html"/>
    <LogoutInitiator type="Local"/>
  </LogoutInitiator>
  <!-- other things -->
</Sessions>

Then your

  • Login URL is: http(s?)://your_fully_qualified_domain_name/Shibboleth.sso/Login
  • Logout URL is: http(s?)://your_fully_qualified_domain_name/Shibboleth.sso/Logout
Note: Most common errors are (please check Shibboleth documentation):
  • using http when your Shibboleth SP is configured for https only (either by Apache settings or thehandlerSSL parameter)
  • you want to use another SessionInitiator (for example with Discovery Service), such as /DS


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 $_SERVER headers, see #Attribute settings right above. On new user creation a random password is generated. This can be overwritten by the user unless you disallow it by the userprotect module.

Note: 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.


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 eduPersonTargetedId, 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.

  1. Install Drupal User Protect module
  2. At Administer -> User management -> User Protect -> Protected roles tab check password for the authenticated user role.
  3. At Administer -> Permissions -> userprotect module: uncheck change own password for authenticated user
  4. 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.

  1. Enable Shibboleth protection
  2. Login with your own user credentials, so that your Drupal user profile is created
  3. Disable Shibboleth protection
  4. Login as 'admin', grant your own user 'Administrator' rights.
  5. Enable Shibboleth protection
  6. Login with your own credentials, you should have 'Administrator' rights now.

Dynamic role assignment

It's possible to assign roles to users based on their Shibboleth attributes.

An assignment rule is made of three parameters:

  • $_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 to the matching users

Revoking/adding a Shibboleth attribute rule will take effect immediately on next page refresh. The same applies when the set of headers is happened to be changed.

Note: although dynamic roles are NOT displayed on the user page, the permissions assigned to the role are in effect for the user.
This is a feature, not a bug

Additional roles can be assigned statically to the user (as an individual) by the administrator as normally. Every logged in user gets the role Authenticated user automatically.

Account linking

There might be cases when you have a number of existing users and you want them to (optionally) log in through the federation. If you enable account linking, a user can add her SSO login to her existing Drupal account. The process of adding an SSO login -> Drupal account association is the following (all steps are performed by the user):

  1. Login to Drupal (with username/password)
  2. Go to My account -> Edit
  3. Click on Link this account to Shibboleth!
  4. Authenticate with your IdP

From this point the user can choose to login either with Shibboleth or with username/password. This feature can also be useful for users switching home organizations.


Dynamic roles are roles based on server variables, not users. These may well be different on username/password logon and Shibboleth logon.

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 have a valid session.)


URL to redirect to after logout

Define an URL here, where you want the user to be navigated after logout. The URL can be absolute or relative to the server base url. The relative paths will be automatically extended with the site base URL.

SAML2 Logout

At the moment, Shibboleth2 SP supports SAML2 logout while the Shibboleth2 IdP does not. It has a consequence that (if you have a standard Shibboleth2 installation), you will get a Shibboleth error message on logout, like this:

Global Logout
Status of Global Logout: Identity provider does not support SAML 2 Single Logout protocol.

You can avoid this message by commenting out SAML2 global logout initiator from /Logout handler in /etc/shibboleth/shibboleth2.xml:

 <!-- LogoutInitiators enable SP-initiated local or global/single logout of sessions. -->
 <LogoutInitiator type="Chaining" Location="/Logout" relayState="cookie">
   <!-- The following line should be commented out to make Drupal logout work,
        as long as your IdPs do not support SAML2 logout -->
   <!--LogoutInitiator type="SAML2" template="bindingTemplate.html"/-->
   <LogoutInitiator type="Local"/>
 </LogoutInitiator>

User consent

In certain scenarios you are only allowed to store personal data if the user accepted some kind of legal agreement such as the Terms of Use or the Privacy Policy.

When a new user arrives, she gets a screen with a link to the legal document and a checkbox. This page also contains the user's name and the e-mail address. Personal data required for login are stored only if the user accepts the agreement. If it's allowed by the administrator, the user might set custom values for those attributes.

If the document changes, the administrator might increment the version. This case all users are forced to accept the new version of the agreement before logging in.

Note: Version matching is an exact match, so the user must accept exactly the same version what was specified by the administrator

Personal data handled by the module

  • username
  • user's e-mail address
  • user's targeted identifier(s) (what is sent by the IdP, if different from username), along with a mapping to the Drupal username
  • Identity Provider(s) that identified the user
  • random password (this might not be considered personal data)
  • time of the registration

Change log

Version 3.0 -> 3.1

If you need documentation for 3.0, please use the previous version of the documentation

Release notes

Version 4.0

Bug fixes
  • The module now works with caching enabled
New features
  • Allow specifying Drupal username, thus support opaque identifiers
  • Support account linking