auth/shibboleth/README.txt

   1 Shibboleth Authentication for Moodle
   2 -------------------------------------------------------------------------------
   3
   4 Requirements:
   5 - Shibboleth target 1.1 or later. See documentation for your Shibboleth
   6   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
  24 Moodle Configuration with Dual login
  25 -------------------------------------------------------------------------------
  26 1. Protect the directory moodle/auth/shibboleth/index.php with Shibboleth.
  27    The page index.php in that directory actually logs in a Shibboleth user.
  28    For Apache you have to define a rule like the following in the Apache config:
  29
  30 --
  31 <Location ~  "/auth/shibboleth/index.php">
  32         AuthType shibboleth
  33         ShibRequireSession On
  34         require valid-user
  35 </Location>
  36 --
  37
  38    To restrict access to Moodle, replace the access rule 'require valid-user'
  39    with something that fits your needs, e.g. 'require affiliation student'.
  40
  41    For IIS you have protect the auth/shibboleth directory directly in the
  42    RequestMap of the Shibboleth configuration file (shibboleth.xml). See
  43
  44    https://spaces.internet2.edu/display/SHIB/xmlaccesscontrol?topic=XMLAccessControl
  45
  46 2. As Moodle admin, go to the 'Administrations >> Users >> Authentication
  47    Options' and click on the the 'Shibboleth' settings.
  48
  49 3. Fill in the fields of the form. The fields 'Username', 'First name',
  50    'Surname', etc. should contain the name of the environment variables of the
  51    Shibboleth attributes that you want to map onto the corresponding Moodle
  52    variable (e.g. 'HTTP_SHIB_PERSON_SURNAME' for the person's last name, refer
  53    the Shibboleth documentation or the documentation of your Shibboleth
  54    federation for information on which attributes are available).
  55    Especially the 'Username' field is of great importance because
  56    this attribute is used for the Moodle authentication of Shibboleth users.
  57
  58    #############################################################################
  59    Shibboleth Attributes needed by Moodle:
  60    For Moodle to work properly Shibboleth should at least provide the attribute
  61    that is used as username in Moodle. It has to be unique for all Shibboleth
  62    Be aware that Moodle converts the username to lowercase. So, the overall
  63    behaviour of the username will be case-insensitive.
  64    All attributes used for moodle must obey a certain length, otherwise Moodle
  65    cuts off the ends. Consult the Moodle documentation for further information
  66    on the maximum lengths for each field in the user profile.
  67    #############################################################################
  68
  69 4.a  If you want Shibboleth as your only authentication method with an external
  70      Where Are You From (WAYF) Service , set the 'Alternate Login URL' in the
  71      'Common settings' in 'Administrations >> Users >> Authentication Options'
  72      to the the URL of the file 'moodle/auth/shibboleth/index.php'.
  73      This will enforce Shibboleth login.
  74
  75 4.b If you want to use the Moodle internal WAYF service, you have to activate it
  76     in the Moodle Shibboleth authentication settings by checking the
  77     'Moodle WAYF Service' checkbox and providing a list of entity IDs in the
  78     'Identity Providers' textarea together with a name and an optional
  79     SessionInitiator URL, which usually is an absolute or relative URL pointing
  80     to the same host. If no SessionInitiator URL is given, the default one
  81     '/Shibboleth.sso' will be used.
  82     Also see https://spaces.internet2.edu/display/SHIB/SessionInitiator
  83
  84     Important Note: If you upgraded from a previous version of Moodle and now
  85                     want to use the integrated WAYF, you have to make sure that
  86                     in step 1 only the index.php script in
  87                     moodle/auth/shibboleth/ is protected but *not* the other
  88                     scripts and especially not the login.php script.
  89
  90 5.  Save the changes for the 'Shibboleth settings'. T
  91
  92     Important Note: If you went for 4.b (integrated WAYF service), saving the
  93                     settings will overwrite the Moodle Alternate Login URL
  94                     using the Moodle web root URL.
  95
  96 6.  If you want to use Shibboleth in addition to another authentication method
  97     not using the integrated WAYF service from 4.b, change the 'Instructions' in
  98     'Administrations >> Users >> Manage authentication' to contain a link to the
  99      moodle/auth/shibboleth/index.php file which is protected by
 100      Shibboleth (see step 1.) and causes the Shibboleth login procedure to start.
 101      You can also use HTML code in that field, e.g. to include an image as a
 102      Shibboleth login button.
 103
 104      Note: As of now you cannot use dual login together with the integrated
 105            WAYF service provided by Moodle (4.b).
 106
 107 7. Save the authentication changes.
 108
 109 How the Shibboleth authentication works
 110 --------------------------------------------------------------------------------
 111 To get Shibboleth authenticated in Moodle a user basically must access the
 112 Shibboleth-protected page /auth/shibboleth/index.php. If Shibboleth is the only
 113 authentication method (see 4.a), this happens automatically when a user selects
 114 his home organization in the Moodle WAYF service or if the alternate login URL
 115 is configured to be the protected /auth/shibboleth/index.php
 116 Otherwise, the user has to click on the link on the dual login page you
 117 provided in step 5.b.
 118
 119 Moodle basically checks whether the Shibboleth attribute that you mapped
 120 as the username is present. This attribute should only be present if a user is
 121 Shibboleth authenticated.
 122
 123 If the user's Moodle account has not existed yet, it gets automatically created.
 124
 125 To prevent that every Shibboleth user can access your Moodle site you have to
 126 adapt the 'require valid-user' line in your webserver's config  (see step 1) to
 127 allow only specific users. If you defined some authorization rules in step 1,
 128 these are checked by Shibboleth itself. Only users who met these rules
 129 actually can access /auth/shibboleth/index.php and get logged in.
 130
 131 You can use Shibboleth AND another authentication method (it was tested with
 132 manual login). So, if there are a few users that don't have a Shibboleth
 133 login, you could create manual accounts for them and they could use the manual
 134 login. For other authentication methods you first have to configure them and
 135 then set Shibboleth as your authentication method. Users can log in only via one
 136 authentication method unless they have two accounts in Moodle.
 137
 138 Shibboleth dual login with custom login page
 139 --------------------------------------------------------------------------------
 140 You can create a dual login page that better fits your needs. For this
 141 to work, you have to set up the two authentication methods (e.g. 'Manual
 142 Accounts' and 'Shibboleth') and specify an alternate login link to your own dual
 143 login page. On that page you basically need a link to the Shibboleth-protected
 144 page ('/auth/shibboleth/index.php') for the Shibboleth login and a
 145 form that sends 'username' and 'password' to moodle/login/index.php. Set this
 146 web page then als alternate login page.
 147 Consult the Moodle documentation for further instructions and requirements.
 148
 149 How to customize the way the Shibboleth user data is used in Moodle
 150 --------------------------------------------------------------------------------
 151 Among the Shibboleth settings in Moodle there is a field that should contain a
 152 path to a php file that can be used as data manipulation hook.
 153 You can use this if you want to further process the way your Shibboleth
 154 attributes are used in Moodle.
 155
 156 Example 1: Your Shibboleth federation uses an attribute that specifies the
 157            user's preferred language, but the content of this attribute is not
 158            compatible with the Moodle data representation, e.g. the Shibboleth
 159            attribute contains 'German' but Moodle needs a two letter value like
 160            'de'.
 161 Example 2: The country, city and street are provided in one Shibboleth attribute
 162            and you want these values to be used in the Moodle user profile. So
 163            You have to parse the corresponding attribute to fill the user fields.
 164
 165 If you want to use this hook you have to be a skilled PHP programmer. It is
 166 strongly recommended that you take a look at the file
 167 moodle/auth/shibboleth/auth.php, especially the function 'get_userinfo'
 168 where this file is included.
 169 The context of the file is the same as within this login function. So you
 170 can directly edit the object $result.
 171
 172 Example file:
 173
 174 --
 175 <?PHP
 176
 177     // Set the zip code and the adress
 178     if ($_SERVER[$this->config->field_map_address] != '')
 179     {
 180         // $address contains something like 'SWITCH$Limmatquai 138$CH-8021 Zurich'
 181         // We want to split this up to get:
 182         // institution, street, zipcode, city and country
 183         $address = $_SERVER[$this->config->field_map_address];
 184         list($institution, $street, $zip_city) = split('\$', $address);
 185         ereg(' (.+)',$zip_city, $regs);
 186         $city = $regs[1];
 187
 188         ereg('(.+)-',$zip_city, $regs);
 189         $country = $regs[1];
 190
 191         $result["address"] = $street;
 192         $result["city"] = $city;
 193         $result["country"] = $country;
 194         $result["department"] = $institution;
 195         $result["description"] = "I am a Shibboleth user";
 196
 197     }
 198
 199 ?>
 200 --
 201
 202 --------------------------------------------------------------------------------
 203 In case of problems and questions with Shibboleth authentication, contact
 204 Lukas Haemmerle <lukas.haemmerle@switch.ch> or Markus Hagman <hagman@hytti.uku.fi>