IAM / Projects / Shibboleth / Service Candidates / Moodle
Shibboleth Authentication for Moodle (from the README.txt file in Moodle distribution)
Requirements:
- Shibboleth Service Provider 1.3 or newer. Recommended is 2.1 or newer. See documentation for your Shibboleth federation on how to set up Shibboleth.
Changes:
- 11. 2004: Created by Markus Hagman
- 05. 2005: Modifications to login process by Martin Dougiamas
- 05. 2005: Various extensions and fixes by Lukas Haemmerle
- 06. 2005: Adaptions to new field locks and plugin config structures by Martin
Langhoff and Lukas Haemmerle
- 10. 2005: Added better error messages and moved text to language directories
- 02. 2006: Simplified authentication so that authorization works properly
Added instructions for IIS
- 11. 2006: User capabilities are now loaded properly as of Moodle 1.7+
- 03. 2007: Adapted authentication method to Moodle 1.8
- 07. 2007: Fixed a but that caused problems with uppercase usernames
- 10. 2007: Removed the requirement for email address, surname and given name
attributes on request of Markus Hagman
- 11. 2007: Integrated WAYF Service in Moodle
- 12. 2008: Shibboleth 2.x and Single Logout support added
- 1. 2008: Added logout hook and moved Shibboleth config strings to utf8 auth
language files.
- 3. 2009: Added various improvements and bug fixes reported by Ina Moller from
university Tuebingen and Peter Ellis of University of Washington
- 4. 2009: Added another requirement for logout regarding the call back script
- 6. 2009: Changed handler URL when integrated Discovery Service is used
- 10. 2009: Fixed HTML entity preservation in Shibboleth settings
Moodle Configuration with Dual login
- Protect the directory moodle/auth/shibboleth/index.php with Shibboleth. The page index.php in that directory actually logs in a Shibboleth user. For Apache you have to define a rule like the following in the Apache config:
<Directory /path/to/moodle/auth/shibboleth/index.php>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>
To restrict access to Moodle, replace the access rule 'require valid-user' with something that fits your needs, e.g. 'require affiliation student'.
For IIS you have protect the auth/shibboleth directory directly in the RequestMap of the Shibboleth configuration file (shibboleth.xml or shibboleth2.xml).
<Path name="moodle" requireSession="false" >
<Path name="auth/shibboleth/index.php" requireSession="true" >
<AccessControl>
...
</AccessControl>
</Path>
</Path>
Also see: https://spaces.internet2.edu/display/SHIB2/NativeSPRequestMapper and https://spaces.internet2.edu/display/SHIB2/NativeSPAccessControl
- As Moodle admin, go to the 'Administrations >> Users >> Authentication' and click on the the 'Shibboleth' settings.
- Fill in the fields of the form. The fields 'Username', 'First name', 'Surname', etc. should contain the name of the environment variables of the Shibboleth attributes that you want to map onto the corresponding Moodle variable (e.g. 'Shib-Person-surname' for the person's last name, refer the Shibboleth documentation or the documentation of your Shibboleth federation for information on which attributes are available). Especially the 'Username' field is of great importance because this attribute is used for the Moodle authentication of Shibboleth users.
############################################################################# Shibboleth Attributes needed by Moodle: For Moodle to work properly Shibboleth should at least provide the attribute that is used as username in Moodle. It has to be unique for all Shibboleth Be aware that Moodle converts the username to lowercase. So, the overall behaviour of the username will be case-insensitive. All attributes used for moodle must obey a certain length, otherwise Moodle cuts off the ends. Consult the Moodle documentation for further information on the maximum lengths for each field in the user profile. #############################################################################
4.a If you want Shibboleth as your only authentication method with an external Where Are You From (WAYF) Service , set the 'Alternate Login URL' in the 'Common settings' in 'Administrations >> Users >> Authentication Options' to the the URL of the file 'moodle/auth/shibboleth/index.php'. This will enforce Shibboleth login.
4.b If you want to use the Moodle integrated WAYF service, you have to activate it in the Moodle Shibboleth authentication settings by checking the 'Moodle WAYF Service' checkbox and providing a list of entity IDs in the 'Identity Providers' textarea together with a name and an optional SessionInitiator URL, which usually is an absolute or relative URL pointing to the same host. If no SessionInitiator URL is given, the default one '/Shibboleth.sso' (only works for Shibboleth 1.3.x) will be used. For Shibboleth 2.x you have to add '/Shibboleth.sso/DS' as a SessionInitiator. Also see https://spaces.internet2.edu/display/SHIB/SessionInitiator and https://spaces.internet2.edu/display/SHIB2/NativeSPSessionInitiator
Important Note: If you upgraded from a previous version of Moodle and now want to use the integrated WAYF, you have to make sure that in step 1 only the index.php script in moodle/auth/shibboleth/ is protected but *not* the other scripts and especially not the login.php script.
If you were using the integrated WAYF alread with Shibboleth 1.3, it could be that the integrated WAYF is not working anymore after you updated Moodle. The reason is that the implicitly set default SessionInitiator changed in Moodle as well as in Shibboleth. For Shibboleth 1.3 one therefore has to add /Shibboleth.sso as third parameter whereas this is /Shibboleth.sso/DS for Shibboleth 2.x.
- Save the changes for the 'Shibboleth settings'.
Important Note: If you went for 4.b (integrated WAYF service), saving the settings will overwrite the Moodle Alternate Login URL using the Moodle web root URL.
- If you want to use Shibboleth in addition to another authentication method not using the integrated WAYF service from 4.b, change the 'Instructions' in 'Administrations >> Users >> Manage authentication' to contain a link to the moodle/auth/shibboleth/index.php file which is protected by Shibboleth (see step 1.) and causes the Shibboleth login procedure to start. You can also use HTML code in that field, e.g. to include an image as a Shibboleth login button.
Note: As of now you cannot use dual login together with the integrated WAYF service provided by Moodle (4.b).
- Save the authentication changes.
How the Shibboleth authentication works
To get Shibboleth authenticated in Moodle a user basically must access the Shibboleth-protected page /auth/shibboleth/index.php. If Shibboleth is the only authentication method (see 4.a), this happens automatically when a user selects his home organization in the Moodle WAYF service or if the alternate login URL is configured to be the protected /auth/shibboleth/index.php Otherwise, the user has to click on the link on the dual login page you provided in step 5.b.
Moodle basically checks whether the Shibboleth attribute that you mapped as the username is present. This attribute should only be present if a user is Shibboleth authenticated.
If the user's Moodle account has not existed yet, it gets automatically created.
To prevent that every Shibboleth user can access your Moodle site you have to adapt the 'require valid-user' line in your webserver's config (see step 1) to allow only specific users. If you defined some authorization rules in step 1, these are checked by Shibboleth itself. Only users who met these rules actually can access /auth/shibboleth/index.php and get logged in.
You can use Shibboleth AND another authentication method (it was tested with manual login). So, if there are a few users that don't have a Shibboleth login, you could create manual accounts for them and they could use the manual login. For other authentication methods you first have to configure them and then set Shibboleth as your authentication method. Users can log in only via one authentication method unless they have two accounts in Moodle.
Shibboleth dual login with custom login page
You can create a dual login page that better fits your needs. For this to work, you have to set up the two authentication methods (e.g. 'Manual Accounts' and 'Shibboleth') and specify an alternate login link to your own dual login page. On that page you basically need a link to the Shibboleth-protected page ('/auth/shibboleth/index.php') for the Shibboleth login and a form that sends 'username' and 'password' to moodle/login/index.php. Set this web page then als alternate login page. Consult the Moodle documentation for further instructions and requirements.
How to customize the way the Shibboleth user data is used in Moodle
Among the Shibboleth settings in Moodle there is a field that should contain a path to a php file that can be used as data manipulation hook. You can use this if you want to further process the way your Shibboleth attributes are used in Moodle.
Example 1: Your Shibboleth federation uses an attribute that specifies the user's preferred language, but the content of this attribute is not compatible with the Moodle data representation, e.g. the Shibboleth attribute contains 'German' but Moodle needs a two letter value like 'de'.
Example 2: The country, city and street are provided in one Shibboleth attribute and you want these values to be used in the Moodle user profile. So You have to parse the corresponding attribute to fill the user fields.
If you want to use this hook you have to be a skilled PHP programmer. It is strongly recommended that you take a look at the file moodle/auth/shibboleth/auth.php, especially the function 'get_userinfo' where this file is included. The context of the file is the same as within this login function. So you can directly edit the object $result.
Example file:
--
<?PHP
// Set the zip code and the adress
if ($_SERVER[$this->config->field_map_address] != '')
{
// $address contains something like 'SWITCH$Limmatquai 138$CH-8021 Zurich'
// We want to split this up to get:
// institution, street, zipcode, city and country
$address = $_SERVER[$this->config->field_map_address];
list($institution, $street, $zip_city) = explode('$', $address);
preg_match('/ (.+)/', $zip_city, $regs);
$city = $regs[1];
preg_match('/(.+)-/',$zip_city, $regs);
$country = $regs[1];
$result["address"] = $street;
$result["city"] = $city;
$result["country"] = $country;
$result["department"] = $institution;
$result["description"] = "I am a Shibboleth user";
}
?>
--
How to upgrade your Service Provider to 2.x
In case your upgrade your Service Provider 1.3.x to 2.x, be aware of the fact that in version 2.0 the default behaviour regarding attribute propagation changed. While the Service Provider 1.3.x published the Shibboleth attributes to the web server environment as HTTP Request headers, the Service Provider 2.x publishes attributes as environment variables, which increases the security for some platforms. However, this change has the effect that the attribute names change. E.g. while the surname attribute was published as 'HTTP_SHIB_PERSON_SURNAME' with 1.3.x, this attribute will be available in $_SERVER['Shib-Person-surname'] or depending on your /etc/shibboleth/attribute-map.xml file just as $_SERVER['sn']. Because Moodle needs to know what Shibboleth attributes it shall map onto which Moodle user profile field, one has to make sure the mapping is updated as well after the Service Provider upgrade.
Because you risk locking yourself out of Moodle it is strongly recommended to use the following approach when upgrading the Service Provider:
- Enable manual authentication before the upgrade.
- Make sure that you have at least one manual account with administration privileges working before upgrading your Service Provider to 2.x.
- After the SP upgrade, use this account to log into Moodle and adapt the attribute mapping in 'Site Administration -> Users -> Shibboleth' to reflect the changed attribute names. You find the attribute names in the file /etc/shibboleth/attribute-map.xml listed as the 'id' value of an attribute definition.
- If you are using the integrated WAYF, you may have to set the third parameter of each entry to '/Shibboleth.sso/DS'
- Test the login with a Shibboleth account
- If all is working, disable manual authentication again
How to add logout support
In order make Moodle support Shibboleth logout, one has to make the Shibboleth Service Provider (SP) aware of the Moodle logout capability. Only then the SP can trigger Moodle's front or back channel logout handler.
To make the SP aware of the Moodle logout, you have to add the following to the Shibboleth main configuration file shibboleth2.xml (usually in /etc/shibboleth/) just before the
<MetadataProvider>
element.
<Notify
Channel="back"
Location="https://#YOUR_MOODLE_HOSTNAME#/moodle/auth/shibboleth/logout.php" />
Then restart the Shibboleth daemon and check the log file for errors. If there were no errors, you can test the logout feature by accessing Moodle, authenticating via Shibboleth and the access the URL: #YOUR_MOODLE_HOSTNAME#/Shibboleth.sso/Logout (assuming you have a standard Shibboleth installation). If everything worked well, you should see a Shibboleth page saying that you were successfully logged out and if you go back to Moodle you also should be logged out from Moodle.
Requirements:
- PHP needs the Soap Extension, which maybe must installed manually: More information is available here http://ch.php.net/soap
- Logout only works with Shibboleth Service Provider 2.1 or higher
- /moodle/auth/shibboleth/logout.php *must not* be protected by Shibboleth! In case all of Moodle is protected with Shibboleth, you have to add something like this to your Apache configuration after all the other require rules
<Directory /path/to/moodle/auth/shibboleth/logout.php>
AuthType shibboleth
ShibRequireSession Off
require shibboleth
</Directory>
When using IIS, the same can be achieved by something like:
<Path name="auth/shibboleth/logout.php" requireSession="false" >in the shibboleth2.xml RequestMap?.
Limitations: Single Logout is only supported when SAML2 is used at the SP and the IdP. As of October 2009, the Shibboleth Identity Provider 2.1.4 does not yet support Single Logout (SLO). Therefore, the single logout feature cannot be used yet in a Shibboleth only setup but there may be other SAML2 products that could be used as Identity Provider, e.g. SimpleSAML PHP. One of the reasons why SLO isn't supported yet is because there aren't many applications yet that were adapted to support front and back channel logout. Hopefully, the Moodle logout helps to motivate the developers to implement SLO. On the other hand, the easiest and safest way to log out still is to tell users to quit their web browsers :)
Also see https://spaces.internet2.edu/display/SHIB2/SLOIssues and https://spaces.internet2.edu/display/SHIB2/NativeSPLogoutInitiator for some background information on this topic.
In case of problems and questions with Shibboleth authentication, contact Lukas Haemmerle <lukas.haemmerle@…> or Markus Hagman <hagman@…>
