Changes between Initial Version and Version 1 of MoodleShib


Ignore:
Timestamp:
03/12/13 10:20:54 (8 years ago)
Author:
dabantz@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • MoodleShib

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