Módosítások

== Installation and bootstrapping =={{STOP|This document is written for module version 4The following documentation assumes that* You [https://wiki.0-x ('''development branch''')shibboleth. Please consult the net/confluence/display/SHIB2/FlowsAndConfig understand how Shibboleth works]* You have [[#Change loghttps://wiki.shibboleth.net/confluence/display/SHIB2/Installation successfully installed and configured Shibboleth SP]] for the revisions of this document for the previous releaseson your host running Drupal.}} == Installation = Installing the module ===

==== Compatibility ====Module is being developed for Drupal 6The module assumes that you use Shibboleth SP 2.x. We have stopped backporting new features It's possible to use the 5module with Shibboleth SP 1.x branch and Drupal 7 3, but that version is not yet supported as long as it isn't the stable branchanymore. 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.}}==== Moving from Drupal 6 to Drupal 7 ====To migrate your working installation to D7, first you must update your module to the latest 4.x version. After that, you can perform the Drupal update.===Get it running = Configuration ====== Configuring Shibboleth ====You should be familiar with protecting resources with Shibboleth before using this module. (See [https://spaceswiki.internet2shibboleth.edunet/confluence/display/SHIB2/NativeSPProtectContent 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 [[Drupal Shibboleth module#DEBUG mode | DEBUG mode]] to dump the whole '''$_SERVER''' array. If you can see Shibboleth attributes there, you're fine.

* '''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''.

* '''"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:''' {{NOTE_EN|this example uses lazy sessions. Configuration for Shibboleth 1.3 is quite similar.}}

 {{ATTENTION_EN|You '''MUST''' use <code>ShibUseHeaders On</code> if you use Shibboleth2 with '''<code>mod_rewrite</code>'''. <code>mod_rewrite</code> prefixes CGI environment variables with '''<code>REDIRECT_</code>''', so you have to instruct Shibboleth2 to use headers instead. 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, '''$_SESSION''' arrays and additionally the '''$user''' object, if the user is logged in. This mode shows you all the available attributes and helps you diagnosing possible Shibboleth attribute problems.

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

==== 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 is constituted of the following:* protocol scheme (<code>http://</code> or <code>https://</code>)* host name * Shibboleth handler URL (usually: <code>/which depends on your Shibbolethconfiguration.sso</code>)* 'location' part of the SessionInitiator definition

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

For this example, you should configure the Shibboleth settings of the module as the following:Then your * '''Login URL''' is: <code>http(s?)://your_fully_qualified_domain_name/Shibboleth.sso/Login</code>* ''' for Logout URL''Handler URL''is: <code>http(s?)://your_fully_qualified_domain_name/Shibboleth.sso/Logout</code>{{NOTE_EN| Most common errors are (please check Shibboleth documentation)::::* using ''http'HTTPS'when your Shibboleth SP is configured for '' or https''only (either by Apache settings or the'HTTP'handlerSSL'' parameter):::* you want to use another SessionInitiator (for ''scheme''example with Discovery Service), depending on whether you are using SSL or notsuch as <code>/DS</code>* '''/Login''' for ''WAYF location''}}

===== Attribute settings =====

===== Redirecting authenticated users to HTTPS =====It's a common problem if Shibboleth SP is configured on HTTPS only (<code>handlerSSL="true"</code>), while the site also works on plain HTTP. By using ''Force HTTPS on login'' feature, you can redirect your users to HTTPS at login time. This way you can have your anonymous users view your site unencrypted (which saves some CPU cycles), but once they login, they get redirected to HTTPS (which is the only secure use of Shibboleth SP). {{NOTE_EN|If you don't see Shibboleth attributes in DEBUG although you have double checked that you have set <code>AuthType shibboleth</code>, <code>require shibboleth</code> in your <code>.htaccess</code> file, you most probably need to turn this feature on.}} == 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 =====

* If you enable and later disable the options, the two behave a bit differently. On subsequent logons:

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.)

* if the Shibboleth session is lost, all the Shibboleth-derived attributes disappear, therefore the user loses the [[#Automatic Dynamic role assignment|assigned Shibboleth dynamic roles]]** on the other handare lost, the roles assigned to the ''Drupal account of the user'' persist as long as the Drupal session is validtoo* Shibboleth session might get lost if you use a clustered SP without a central session cache* '''Never ever leave this option off if you want support Single Logout'''. Otherwise the user will remain logged in to Drupal even after doing single (global) logout.}}

=== Dynamic role assignment User consent ===It's possible In certain scenarios you are only allowed to assign roles to users based on their Shibboleth attributesstore personal data if the user accepted some kind of legal agreement such as the Terms of Use or the Privacy Policy.

An assignment rule is made of three parameters:* 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'''$_SERVER''' header name: s name of and the Shibbolethe-derived attribute* '''Value regexp''': regexp applied to (all) mail address. Personal data required for login are stored only if the value(s) of user accepts the Shibboleth-derived attribute* ''agreement. If it'Role(s)''': checklist of roles to be assigned allowed by the administrator, the user might set [[#Using_custom_values | custom values]] for the matching usersthose attributes.

All these rules If the document changes, the administrator might increment the version. This case all users are evaluated at module initiation timeforced to accept the new version of the agreement before logging in. That means that revoking/adding a Shibboleth attribute rule will take effect immediately on next page refresh. The {{NOTE_EN|Version matching is an exact match, so the user must accept exactly the same applies when version what was specified by the administrator}}==== Personal data handled by the set of headers module ====* username* user's e-mail address* user's targeted identifier(s) (what is happened 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 changed.considered personal data)* time of the registration

=== Advanced SAML2 features ===SAML2 defines several properties of the authentication request message which may affect the authentication performed by the IdP.{{NOTE_ENSTOP|Although dynamic roles are '''NOTBe careful when using these options.''' 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 IdPs that do not support these features might signal an error instead of performing any kind of authentication of the user. Or might show errors ''after'' authenticating the user. Some kind of authentication handlers (ie. HTTP Basic Auth) will never work even if the IdP software is capable of handling these properties. }}==== isPassive ====If <code>isPassive</code> is set, then the user is redirected to the IdP or to the Discovery Service in advance, but neither of them are allowed to take over the control of the user interface (such as performing any visible authentication). If authentication (or IdP selection) can not be performed silently, an individual) error is returned, which is then handled by the administrator as normallymodule.

== Using module ===== Automatic user creation ===Drupal CMS requires all By using this option, you can auto-login users who are already logged in to be in its internal SQL databasethe IdP even if you are using lazy sessions. If auto-login can not be performed, the module detects that no user exists in the database with the received Shibboleth user identifier, it creates a new (Drupal) user. === Disallowing password change ===There is no way for the module returns to detect if a user has been deleted from Shibboleth. This simple fact has a number of consequences. When a user is first logged in, a Drupal account is automatically created for her. Because Drupal requires a password, a random string is generated for password. Normally the user doesn't need itunauthenticated without seeing any error message.

Now suppose that your user is about {{ATTENTION_EN|You need to instruct Shibboleth to leave your institution. If she is malicious enough, she can go redirect errors back to the password change form, reset her password Drupal to a known one, and even after she handle passive authentication failures. This is deleted from the IdP, she still can log done by setting <code>redirectErrors</code> parameter in to your precious resource with the (now known) passwordRequestMap. (Note that it is only achievable with lazy sessions!)See [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPContentSettings Shibboleth wiki] for details.

Therefore, if your requirements are such that only Shibboleth-authenticated users can log in, '''YOU MUST DISABLE PASSWORD CHANGEIMPORTANT''' : current implementation does not handle any errors except for usersNoPassive error. This means, that on every possible Shibboleth SP error you will get an unauthenticated Drupal page instead of a Shibboleth error page.}}{{NOTE_EN|this feature requires JavaScript.}}==== forceAuthn ====This feature requires reauthentication of the user at the IdP even if she is having an SSO session there. Just like isPassive, it's not generally supported by authentication handlers.

;Steps for disallowing your users to change their passwords:# Install Drupal [http://drupal.org/project/userprotect User Protect module]# At Administer -> User management -> User Protect -> Protected roles tab check '''password''' for the 'In general, you should never mix 'authenticated user'' role.# At Administer -> Permissions -> userprotect module: uncheck 'isPassive''change own password'and '' for 'forceAuthn'authenticated user''# Log . The standard states that in with a normal accountthis case, go to "My account" -> Edit. You shouldn't see the possibility for changing password; except for IdP must reauthenticate the case when user without visibly taking control of the user has user administrator rightsinterface.=== Administrator / password login ===If It's up to you are using lazy sessions, how you can still login with passwordinterpret it... If you disabled the username/password login block, append the following to your normal Drupal URL: <code>/?q=user</code>==== Administering Drupal with strict sessions Non-implemented features ====If There are several other SAML features which are not yet implemented, because there seems to be very little practical interest for them. Please file a feature request if you use strict sessionsreally need them, but before doing so, you please, spend a little time on thinking how things should really work.* '''AuthnContextClass''': the SP can not log in with a passwordrequest some specific authentication context from the IdP. It* '''NameID management''': the IdP can request to change the user's quite tricky NameID (targeted identifier) or to circumvent remove it:.# Enable Shibboleth protection# Login with your own user credentials, so that your Drupal user profile is created# Disable Shibboleth protection# Login as * '''adminLogout notification', grant your own user 'Administrator' rights: this is a Shibboleth2 feature, not a SAML one.# Enable You generally do not need this, because you can terminate the Drupal session on Shibboleth protection# Login with your own credentialssession expiry. This workaround has the disadvantage that the module will not be notified at the time when the user was logged out, you should have 'Administrator' rights nowonly on the next page refresh.

* Support for sticky rules (roles saved permanently to the users' profile)* Basic support for account linking* Basic support for getting user consent on personal data* Support for isPassive and forceAuthn session initiation* Support for redirecting users to HTTPS on login

[[Category: AAI]] [[Category: Drupal]] [[Category: Shibboleth SP]] [[Category: HOWTO]] [[Category: English]]