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