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