Shibboleth
This page requires updating. Please do so and remove this template when finished.
Location: Settings link in Settings > Site administration > Plugins > Authentication > Manage authentication
Shibboleth is a middleware architecture and an open-source implementation created by the Internet2 consortium, for federated identity-based authentication and authorization infrastructure based on SAML. Federated identity allows for information about users in one security domain to be provided to other organizations in a common federation. This allows for cross-domain single sign-on and removes the need for content providers to maintain usernames and passwords. Identity providers (IdP's) supply user information, while service providers (SP's) consume this information and gate access to secure content.
Source: Wikipedia, Shibboleth_(software)
Configuring Moodle to use Shibboleth
The auth/shibboleth/README.txt file in the in your Moodle distribution contains set-up instructions. Your web server might allow to view it in browser under YOURSITE/auth/shibboleth/README.txt.
Shibboleth in the UK
In the UK Becta and JISC have implemented an education federation using Shibboleth to provide single sign on. This means that education establishments in the UK using Moodle should be able to authenticate their users via Shibboleth if their organization joins the UK Access Management Federation and their users' identity is held by the identity provider the LA/RBC use. For maintained schools in the England and Wales this will probably mean contacting their Local Authority or Regional Broadband Consortium (RBC). A list of current UK federation members can be found here.
Shibboleth in Switzerland
In Switzerland the SWITCH Foundation runs a universal login under edu-ID for all living in Switzerland. It covers 160 institutions and 900,000 users.
A sample configuration
Notation
- The expressions in all caps are placeholders for their actual values. For example /PATH/TO/MOODLE could be /var/www/html/moodle in your server.
- The '#' in shell commands in the form '# COMMAND" means the COMMAND needs to be run as the super-user. It could be the user 'root' or a different user having sudo privileges. In the latter case he should prepend the command with sudo, as in '$ sudo COMMAND'. The '$' in that command denotes it is a non-privileged user.
Prerequisites
- You have your Moodle site running on Debian GNU/Linux or any of its derivatives like Ubuntu Linux.
- This documentation assumes that your Linux distribution uses the system manager Systemd. But you can easily change the commands for a different init system, typically SysV or Upstart.
- You are running the web server Apache2.
- Your site serves HTTPS on its default port 443. We write its URL as https://DOMAIN, where DOMAIN stands for your the domain name of your Moodle server. So if the URL of your Moodle is https://lms.example.com/ then DOMAIN is lms.example.com.
Steps you have to follow
1. Install the Shibboleth module for Apache2
Install the Debian package libapache2-mod-shib, which contains the Apache module for Shibboleth service providers (SP) and its supporting Shib daemon:
# apt install libapache2-mod-shib --no-install-recommends
It will create a directory /etc/shibboleth with a default set of configuration files and also install the system service shib.
2. Download federation metadata signing certificate
# wget https://FEDERATIONREGISTRY/signedmetadata/metadata-signer -O /etc/shibboleth/federation-cert.pem
3. Configure the Shibboleth service provider
Edit the /etc/shibboleth/shibboleth2.xml file as described below.
3.1 Change the ApplicationDefaults tag to your domain
<ApplicationDefaults entityID="https://DOMAIN/shibboleth" REMOTE_USER="eppn subject-id pairwise-id persistent-id" cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">
Notice that the end of the ApplicationDefaults tag is way below. So don't add one here!
3.2 Set the discovery server
<SSO discoveryProtocol="SAMLDS" discoveryURL="https://DISCOVERYSERVER"> SAML2 </SSO>
3.3 Set the MetadataProvider
<MetadataProvider type="XML" url="https://METADATAPROVIDER/signedmetadata/metadata.xml" legacyOrgName="true" backingFilePath="test-metadata.xml" maxRefreshDelay="7200">
<MetadataFilter type="Signature" certificate="federation-cert.pem" verifyBackup="false" />
<MetadataFilter type="RequireValidUntil" maxValidityInterval="864000" />
</MetadataProvider>
3.4 Set the names of the key and certificate files
<CredentialResolver type="File" use="signing" key="lms-signing-key.pem" certificate="lms-signing-cert.pem" />
<CredentialResolver type="File" use="encryption" key="lms-encrypt-key.pem" certificate="lms-encrypt-cert.pem" />
We will generate those lms-*.pem files in step 3.6.
3.5 Add a ApplicationOverride section (Note: Not necessay, dg 28 Aug 2024)
Add the following ApplicationOverride section just before the ApplicationDefaults section:
<ApplicationOverride id="wp" entityID="https://wp.YOUR-DOMAIN/shibboleth"> <CredentialResolver type="File" use="signing" key="wp-signing-key.pem" certificate="wp-signing-cert.pem"/> <CredentialResolver type="File" use="encryption" key="wp-encrypt-key.pem" certificate="wp-encrypt-cert.pem"/> </ApplicationOverride>
3.6 Create SP metadata credentials for both sites:
/usr/sbin/shib-keygen -n lms-signing -e https://DOMAIN/shibboleth /usr/sbin/shib-keygen -n lms-encrypt -e https://DOMAIN/shibboleth
4. Start the shibboleth service
4.1 Test the configuration first:
# shibd -t /etc/shibboleth/shibboleth2.xml
4.2 (Re)start the Shibd and Apache2:
# systemctl start shibd # systemctl restart apache2
5. Enable Shibboleth on the Apache virtual host
5.1 To enable shibboleth login on the web application add the certificate files and protect the /PATH/TO/MOODLE/auth/shibboleth/index.php by Shibboleth. They are in a /etc/apache2/sites-available/SOMETHING.conf file. Here is the format:
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerName DOMAIN
ServerAdmin YOU@DOMAIN
DocumentRoot /PATH/TO/MOODLE
ErrorLog ${APACHE_LOG_DIR}/DOMAIN-error.log
CustomLog ${APACHE_LOG_DIR}/DOMAIN-access.log combined
SSLCertificateFile /etc/ssl/certs/ssl-DOMAIN.crt
SSLCertificateKeyFile /etc/ssl/private/ssl-DOMAIN.key
<Location /moodle>
# just comment out
# ShibRequestSetting applicationId mdl
</Location>
<Directory /PATH/TO/MOODLE/auth/shibboleth/index.php>
AuthType shibboleth
# just comment out the next line and add the two lines below that
# ShibRequestSetting applicationId mdl
ShibRequireSession On
require valid-user
</Directory>
</VirtualHost>
</IfModule>
5.2 Activate Shibd and reload Apache
# a2enmod shib # systemctl reload apache2.service
6. Register the SP with the federation
We have now set up Shibboleth SP for Moodle. It has to be registered with the federation so that its WAYF go to the discovery Service to point different IDP's.
6.1 Download the metadata of the application
You can get them by visiting the URL https://DOMAIN/Shibboleth.sso/Metadata
6.2 Register the metadata with the federation
Visit https://FEDERATTION/ and go to Join. You will be asked to upload the metadata on line and go through a couple of screens answering administrative questions. Follow the instructions on the screens.
Once the federation operator approves your request you will receive a SP registration link.
7. Enable and configure the Shibboleth plug-in in Moodle
Once you've registered successfully you have to configure the Shibboleth plug-in in Moodle. For that Moodle you have to enable it first.
7.1 Enable the Shibboleth plug-in in Moodle
As Moodle admin, go to the Site administration > Plugins > Authentication and enable Shibboleth by clicking on the "eye".
7.2 Configure the Shibboleth plug-in in Moodle
The fields 'Username', 'First name', 'Surname', etc. should contain the name of the environment variables of the Shibboleth attributes that you want to map onto the corresponding Moodle variable. Especially the 'Username' field is of great importance because this attribute is used for the Moodle authentication of Shibboleth users.
Username: eppn
Moodle WAYF service: No
Identity providers (auth_shibboleth | organization_selection): Delete everything in the box
Shibboleth Service Provider logout handler URL: /Shibboleth.sso/Logout
Data mapping (First name): givenName
Data mapping (Surname): sn
Data mapping (Email address): mail
In all three set Update local to On every login and Lock value to Unlocked if empty.
And save. The change will be immediately active, no need to restart any service!
Finished!
Now you may browse to https://DOMAIN/ and select your preferred IdP to log in.
===How to debug
Additional notes
Some IdPs will only share a minimal set of user fields with your Moodle SP, which can cause problems:
- Moodle errors relating to missing Shibboleth fields can be fixed by altering the data mappings within the Shibboleth authentication plugin, and ensuring that fields are not locked. The user will be asked to manually provide data if Shibboleth does not automatically provide the corresponding information.
- Moodle errors relating to invalid characters in username can be fixed by Allowing extended characters in usernames (found under Security > Site policies).
