[Summary view] [Print] [Text view]

   1  Shibboleth Authentication for Moodle
   2  -------------------------------------------------------------------------------
   3  
   4  Requirements:
   5  - Shibboleth Service Provider 1.3 or newer. Recommended is 2.1 or newer.
   6    See documentation for your Shibboleth federation on how to set up Shibboleth.
   7  
   8  Changes:
   9  - 11. 2004: Created by Markus Hagman
  10  - 05. 2005: Modifications to login process by Martin Dougiamas
  11  - 05. 2005: Various extensions and fixes by Lukas Haemmerle
  12  - 06. 2005: Adaptions to new field locks and plugin config structures by Martin
  13              Langhoff and Lukas Haemmerle
  14  - 10. 2005: Added better error messages and moved text to language directories
  15  - 02. 2006: Simplified authentication so that authorization works properly
  16              Added instructions for IIS
  17  - 11. 2006: User capabilities are now loaded properly as of Moodle 1.7+
  18  - 03. 2007: Adapted authentication method to Moodle 1.8
  19  - 07. 2007: Fixed a but that caused problems with uppercase usernames
  20  - 10. 2007: Removed the requirement for email address, surname and given name
  21              attributes on request of Markus Hagman
  22  - 11. 2007: Integrated WAYF Service in Moodle
  23  - 12. 2008: Shibboleth 2.x and Single Logout support added
  24  - 1.  2008: Added logout hook and moved Shibboleth config strings to utf8 auth
  25              language files.
  26  - 3.  2009: Added various improvements and bug fixes reported by Ina M�ller from
  27              university Tuebingen and Peter Ellis of University of Washington
  28  - 4.  2009: Added another requirement for logout regarding the call back script
  29  - 6.  2009: Changed handler URL when integrated Discovery Service is used
  30  - 10. 2009: Fixed HTML entity preservation in Shibboleth settings
  31  
  32  Moodle Configuration with Dual login
  33  -------------------------------------------------------------------------------
  34  1. Protect the directory moodle/auth/shibboleth/index.php with Shibboleth.
  35     The page index.php in that directory actually logs in a Shibboleth user.
  36     For Apache you have to define a rule like the following in the Apache config:
  37  
  38  --
  39  <Directory  /path/to/moodle/auth/shibboleth/index.php>
  40          AuthType shibboleth
  41          ShibRequireSession On
  42          require valid-user
  43  </Directory>
  44  --
  45  
  46     To restrict access to Moodle, replace the access rule 'require valid-user'
  47     with something that fits your needs, e.g. 'require affiliation student'.
  48  
  49     For IIS you have protect the auth/shibboleth directory directly in the
  50     RequestMap of the Shibboleth configuration file (shibboleth.xml or
  51     shibboleth2.xml).
  52  
  53  --
  54  <Path name="moodle" requireSession="false" >
  55     <Path name="auth/shibboleth/index.php" requireSession="true" >
  56        <AccessControl>
  57            ...
  58        </AccessControl>
  59     </Path>
  60  </Path>
  61  --
  62  
  63     Also see:
  64     https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPRequestMapper and
  65     https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAccessControl
  66  
  67  2. As Moodle admin, go to the 'Administrations >> Users >> Authentication' and
  68     click on the the 'Shibboleth' settings.
  69  
  70  3. Fill in the fields of the form. The fields 'Username', 'First name',
  71     'Surname', etc. should contain the name of the environment variables of the
  72     Shibboleth attributes that you want to map onto the corresponding Moodle
  73     variable (e.g. 'Shib-Person-surname' for the person's last name, refer
  74     the Shibboleth documentation or the documentation of your Shibboleth
  75     federation for information on which attributes are available).
  76     Especially the 'Username' field is of great importance because
  77     this attribute is used for the Moodle authentication of Shibboleth users.
  78  
  79     #############################################################################
  80     Shibboleth Attributes needed by Moodle:
  81     For Moodle to work properly Shibboleth should at least provide the attribute
  82     that is used as username in Moodle. It has to be unique for all Shibboleth
  83     Be aware that Moodle converts the username to lowercase. So, the overall
  84     behaviour of the username will be case-insensitive.
  85     All attributes used for moodle must obey a certain length, otherwise Moodle
  86     cuts off the ends. Consult the Moodle documentation for further information
  87     on the maximum lengths for each field in the user profile.
  88     #############################################################################
  89  
  90  4.a  If you want Shibboleth as your only authentication method with an external
  91       Where Are You From (WAYF) Service , set the 'Alternate Login URL' in the
  92       'Common settings' in 'Administrations >> Users >> Authentication Options'
  93       to the the URL of the file 'moodle/auth/shibboleth/index.php'.
  94       This will enforce Shibboleth login.
  95  
  96  4.b If you want to use the Moodle integrated WAYF service, you have to activate it
  97      in the Moodle Shibboleth authentication settings by checking the
  98      'Moodle WAYF Service' checkbox and providing a list of entity IDs in the
  99      'Identity Providers' textarea together with a name and an optional
 100      SessionInitiator URL, which usually is an absolute or relative URL pointing
 101      to the same host. If no SessionInitiator URL is given, the default one
 102      '/Shibboleth.sso' (only works for Shibboleth 1.3.x) will be used. For
 103      Shibboleth 2.x you have to add '/Shibboleth.sso/DS' as a SessionInitiator.
 104      Also see https://wiki.shibboleth.net/confluence/display/SHIB/SessionInitiator
 105      and https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessionInitiator
 106  
 107      Important Note: If you upgraded from a previous version of Moodle and now
 108                      want to use the integrated WAYF, you have to make sure that
 109                      in step 1 only the index.php script in
 110                      moodle/auth/shibboleth/ is protected but *not* the other
 111                      scripts and especially not the login.php script.
 112  
 113      If you were using the integrated WAYF alread with Shibboleth 1.3, it could
 114      be that the integrated WAYF is not working anymore after you updated Moodle.
 115      The reason is that the implicitly set default SessionInitiator changed in
 116      Moodle as well as in Shibboleth. For Shibboleth 1.3 one therefore has to
 117      add /Shibboleth.sso as third parameter whereas this is /Shibboleth.sso/DS
 118      for Shibboleth 2.x.
 119  
 120  
 121  5.  Save the changes for the 'Shibboleth settings'.
 122  
 123      Important Note: If you went for 4.b (integrated WAYF service), saving the
 124                      settings will overwrite the Moodle Alternate Login URL
 125                      using the Moodle web root URL.
 126  
 127  6.  If you want to use Shibboleth in addition to another authentication method
 128      not using the integrated WAYF service from 4.b, change the 'Instructions' in
 129      'Administrations >> Users >> Manage authentication' to contain a link to the
 130       moodle/auth/shibboleth/index.php file which is protected by
 131       Shibboleth (see step 1.) and causes the Shibboleth login procedure to start.
 132       You can also use HTML code in that field, e.g. to include an image as a
 133       Shibboleth login button.
 134  
 135       Note: As of now you cannot use dual login together with the integrated
 136             WAYF service provided by Moodle (4.b).
 137  
 138  7. Save the authentication changes.
 139  
 140  How the Shibboleth authentication works
 141  --------------------------------------------------------------------------------
 142  To get Shibboleth authenticated in Moodle a user basically must access the
 143  Shibboleth-protected page /auth/shibboleth/index.php. If Shibboleth is the only
 144  authentication method (see 4.a), this happens automatically when a user selects
 145  his home organization in the Moodle WAYF service or if the alternate login URL
 146  is configured to be the protected /auth/shibboleth/index.php
 147  Otherwise, the user has to click on the link on the dual login page you
 148  provided in step 5.b.
 149  
 150  Moodle basically checks whether the Shibboleth attribute that you mapped
 151  as the username is present. This attribute should only be present if a user is
 152  Shibboleth authenticated.
 153  
 154  If the user's Moodle account has not existed yet, it gets automatically created.
 155  
 156  To prevent that every Shibboleth user can access your Moodle site you have to
 157  adapt the 'require valid-user' line in your webserver's config  (see step 1) to
 158  allow only specific users. If you defined some authorization rules in step 1,
 159  these are checked by Shibboleth itself. Only users who met these rules
 160  actually can access /auth/shibboleth/index.php and get logged in.
 161  
 162  You can use Shibboleth AND another authentication method (it was tested with
 163  manual login). So, if there are a few users that don't have a Shibboleth
 164  login, you could create manual accounts for them and they could use the manual
 165  login. For other authentication methods you first have to configure them and
 166  then set Shibboleth as your authentication method. Users can log in only via one
 167  authentication method unless they have two accounts in Moodle.
 168  
 169  Shibboleth dual login with custom login page
 170  --------------------------------------------------------------------------------
 171  You can create a dual login page that better fits your needs. For this
 172  to work, you have to set up the two authentication methods (e.g. 'Manual
 173  Accounts' and 'Shibboleth') and specify an alternate login link to your own dual
 174  login page. On that page you basically need a link to the Shibboleth-protected
 175  page ('/auth/shibboleth/index.php') for the Shibboleth login and a
 176  form that sends 'username' and 'password' to moodle/login/index.php. Set this
 177  web page then als alternate login page.
 178  Consult the Moodle documentation for further instructions and requirements.
 179  
 180  How to customize the way the Shibboleth user data is used in Moodle
 181  --------------------------------------------------------------------------------
 182  Among the Shibboleth settings in Moodle there is a field that should contain a
 183  path to a php file that can be used as data manipulation hook.
 184  You can use this if you want to further process the way your Shibboleth
 185  attributes are used in Moodle.
 186  
 187  Example 1: Your Shibboleth federation uses an attribute that specifies the
 188             user's preferred language, but the content of this attribute is not
 189             compatible with the Moodle data representation, e.g. the Shibboleth
 190             attribute contains 'German' but Moodle needs a two letter value like
 191             'de'.
 192  Example 2: The country, city and street are provided in one Shibboleth attribute
 193             and you want these values to be used in the Moodle user profile. So
 194             You have to parse the corresponding attribute to fill the user fields.
 195  
 196  If you want to use this hook you have to be a skilled PHP programmer. It is
 197  strongly recommended that you take a look at the file
 198  moodle/auth/shibboleth/auth.php, especially the function 'get_userinfo'
 199  where this file is included.
 200  The context of the file is the same as within this login function. So you
 201  can directly edit the object $result.
 202  
 203  Example file:
 204  
 205  --
 206  <?php
 207  
 208      // Set the zip code and the adress
 209      if ($_SERVER[$this->config->field_map_address] != '')
 210      {
 211          // $address contains something like 'SWITCH$Limmatquai 138$CH-8021 Zurich'
 212          // We want to split this up to get:
 213          // institution, street, zipcode, city and country
 214          $address = $_SERVER[$this->config->field_map_address];
 215          list($institution, $street, $zip_city) = explode('$', $address);
 216          preg_match('/ (.+)/', $zip_city, $regs);
 217          $city = $regs[1];
 218  
 219          preg_match('/(.+)-/',$zip_city, $regs);
 220          $country = $regs[1];
 221  
 222          $result["address"] = $street;
 223          $result["city"] = $city;
 224          $result["country"] = $country;
 225          $result["department"] = $institution;
 226          $result["description"] = "I am a Shibboleth user";
 227  
 228      }
 229  
 230  ?>
 231  --
 232  
 233  How to upgrade your Service Provider to 2.x
 234  -------------------------------------------------------------------------------
 235  
 236  In case your upgrade your Service Provider 1.3.x to 2.x, be aware of the fact
 237  that in version 2.0 the default behaviour regarding attribute propagation
 238  changed.
 239  While the Service Provider 1.3.x published the Shibboleth attributes to the
 240  web server environment as HTTP Request headers, the Service Provider 2.x
 241  publishes attributes as environment variables, which increases the security for
 242  some platforms.
 243  However, this change has the effect that the attribute names change.
 244  E.g. while the surname attribute was published as 'HTTP_SHIB_PERSON_SURNAME'
 245  with 1.3.x, this attribute will be available in $_SERVER['Shib-Person-surname']
 246  or depending on your /etc/shibboleth/attribute-map.xml file just as
 247  $_SERVER['sn'].
 248  Because Moodle needs to know what Shibboleth attributes it shall map onto which
 249  Moodle user profile field, one has to make sure the mapping is updated as well
 250  after the Service Provider upgrade.
 251  
 252  ********************************************************************************
 253  Because you risk locking yourself out of Moodle it is strongly
 254  recommended to use the following approach when upgrading the Service Provider:
 255  1. Enable manual authentication before the upgrade.
 256  2. Make sure that you have at least one manual account with administration
 257     privileges working before upgrading your Service Provider to 2.x.
 258  3. After the SP upgrade, use this account to log into Moodle and adapt the
 259     attribute mapping in 'Site Administration -> Users -> Shibboleth' to reflect
 260     the changed attribute names.
 261     You find the attribute names in the file /etc/shibboleth/attribute-map.xml
 262     listed as the 'id' value of an attribute definition.
 263  4. If you are using the integrated WAYF, you may have to set the third parameter
 264     of each entry to '/Shibboleth.sso/DS'
 265  5. Test the login with a Shibboleth account
 266  6. If all is working, disable manual authentication again
 267  ********************************************************************************
 268  
 269  How to add logout support
 270  --------------------------------------------------------------------------------
 271  In order make Moodle support Shibboleth logout, one has to make the Shibboleth
 272  Service Provider (SP) aware of the Moodle logout capability. Only then the SP
 273  can trigger Moodle's front or back channel logout handler.
 274  
 275  To make the SP aware of the Moodle logout, you have to add the following to the
 276  Shibboleth main configuration file shibboleth2.xml (usually in /etc/shibboleth/)
 277  just before the <MetadataProvider> element.
 278  
 279  --
 280  <Notify
 281      Channel="back"
 282      Location="https://#YOUR_MOODLE_HOSTNAME#/moodle/auth/shibboleth/logout.php" />
 283  --
 284  
 285  Then restart the Shibboleth daemon and check the log file for errors. If there
 286  were no errors, you can test the logout feature by accessing Moodle,
 287  authenticating via Shibboleth and the access the URL:
 288  #YOUR_MOODLE_HOSTNAME#/Shibboleth.sso/Logout (assuming you have a standard
 289  Shibboleth installation). If everything worked well, you should see a Shibboleth
 290  page saying that you were successfully logged out and if you go back to Moodle
 291  you also should be logged out from Moodle.
 292  
 293  Requirements:
 294  - PHP needs the Soap Extension, which maybe must installed manually:
 295    More information is available here http://ch.php.net/soap
 296  - Logout only works with Shibboleth Service Provider 2.1 or higher
 297  - /moodle/auth/shibboleth/logout.php *must not* be protected by Shibboleth!
 298    In case all of Moodle is protected with Shibboleth, you have to add something
 299    like this to your Apache configuration after all the other require rules
 300  
 301  --
 302  <Directory /path/to/moodle/auth/shibboleth/logout.php>
 303      AuthType shibboleth
 304      ShibRequireSession Off
 305      require shibboleth
 306  </Directory>
 307  --
 308    When using IIS, the same can be achieved by something like:
 309  --
 310  <Path name="auth/shibboleth/logout.php" requireSession="false" >
 311  --
 312    in the shibboleth2.xml RequestMap.
 313  
 314  
 315  Limitations:
 316  Single Logout is only supported when SAML2 is used at the SP and the IdP.
 317  As of October 2009, the Shibboleth Identity Provider 2.1.4 does not yet support
 318  Single Logout (SLO). Therefore, the single logout feature cannot be used yet
 319  in a Shibboleth only setup but there may be other SAML2 products that could
 320  be used as Identity Provider, e.g. SimpleSAML PHP.
 321  One of the reasons why SLO isn't supported yet is because there aren't many
 322  applications yet that were adapted to support front and back channel
 323  logout. Hopefully, the Moodle logout helps to motivate the developers to
 324  implement SLO. On the other hand, the easiest and safest way to log out
 325  still is to tell users to quit their web browsers :)
 326  
 327  Also see https://wiki.shibboleth.net/confluence/display/SHIB2/SLOIssues and
 328  https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLogoutInitiator for some
 329  background information on this topic.
 330  
 331  --------------------------------------------------------------------------------
 332  In case of problems and questions with Shibboleth authentication, contact
 333  Lukas Haemmerle <lukas.haemmerle@switch.ch> or Markus Hagman <hagman@hytti.uku.fi>