3.5. Shibboleth authentication

Shibboleth is a standardized authentication and authorization mechanism. With Shibboleth, the user is redirected to a WAYF/Discovery Service (Where Are You From?), asked to chose her Home Organisation/Identity Provider (her university / company website) to authenticate. The user selects his Home Organization 'University B' and is redirected to its login page. The user sees the familiar login page of 'University B' and provides his login name and password. If login name and password match, the user is redirected back to the resource (e.g. OLAT) he initially requested. After successful authentication at his Home Organization, the resource (OLAT) decides (based on the provided attributes) on granting or denying him access. In the background, the Home Organization provided minimal user details to OLAT, which it requires for the access authorization decision and for delivering its service. See the SWITCH AAI Demo for a Shibboleth Login Procedure summary.

A Shibboleth Service Provider is needed, to protect any resource (e.g. OLAT) on that web server, either with web server access rules or within the application itself. OLAT uses since 6.2.x Shibboleth Service Provider 2.0 with Apache, mod-shib, shibd, mod_jk. The Shibboleth Service Provider Access Rules guideline is found here. A resource either can be protected with acces rules defined in the web server configuration or by the application itself by checking certain Shibboleth attributes. In both cases, a Shibboleth session must be enforced on the file, location or directory to protect. Second, there must be an authorization rule based on attributes that determines how access is granted. If you plan to use the XML access control rules with Apache (e.g. in order to dynamically protect a location), you first have to make sure that the Shibboleth module actually is active for the specific location or the whole web server. This can be done by using a rule in the Apache configuration like the following:

 
			<Location /olat/shib> 
				AuthType shibboleth
    				ShibRequireSession On
    				require valid-user
    				ShibUseHeaders On
  			</Location>

If you wonder what the names are of the attributes you can check for, have a look at the attribute-map.xml file.

The configuration of OLAT Shibboleth Module is done via olat.local.properties / olat_config.xml. The following parameters have to be set:

EnableShibbolethLogins (true/false): If set to "true" Shibboleth will be enabled on your installation.
UniqueIdentifiers: Defines the attributes which allows to uniquely identify an authenticated person. Make sure, values of this attribute are truly unique. It is used to map an identity who has been authenticated by an Identity Provider to an identity within OLAT. The default unique identifier ("<Default />")is mandatory. You may specify unique identifiers on a per-site basis (e.g. <OriginSite siteName="examplesite" uidAttribute="exampleuid" />)
AttributeTranslations (contains Attribute elements): Shibboleth can provide attributes to OLAT after successfull authentication of an identity. These attributes are propagated within OLAT for use e.g. as a pre-condition within a course. To make the attribute names easier to read (and use) you may provide translations to the attributes. E.g. "givenName" reads easier as opposed to "Shib-InetOrgPerson-givenName" (which is the attribute's actual name). See the olat_config.xml.in file for an example. The Service Providers's supported attributes are listed in attribute-map.xml. See below the Shibboleth Service Provider 2.0 installation section.
OLATUserMapping : This section is used to map Shibboleth attributes to user preference attributes within OLAT. After each successfull Shibboleth authentication, the given Shibboleth attributes are mapped to the corresponding attributes in the OLAT user profile. E.g. Shibboleth Attribute "Shib-InetOrgPerson-givenName" would be mapped to the OLAT user profile's first name with the following statement:
```
<FirstName>Shib-InetOrgPerson-givenName</FirstName>
```
Valid mappings are: FirstName, LastName, EMail, InstitutionalName, InstitutionalEMail, InstitutionalUserIdentifier.

Step by step guide to enable Shibboleth 2 on your OLAT installation (without set up of identiy provider):

Install and configure Shibboleth Service Provider 2.0 with Apache, shibd (Shibboleth daemon), mod-shib, mod_jk. Please check the Shibboleth SP Hands-on documentation (see overview image) here. All needed information about directory structure, sanity checks, key/certificate generation, using a Discovery Service, attribute mappings, etc. could be found at the mentioned link. These links might also be useful: Shibboleth 2 Installation and Shibboleth 2 Configuration.
Shibboleth Service Provider for Apache Overview
Get a FQDN (DNS name) for your OLAT installation like: olat.earth.sky
Create an RSA key and out of it create a certificate request using openssl. See example from Swiss Education & Research Network: How to obtain server certificate.
Let the certificate request sign from a certificate authority
Download the signed certificate in the PEM format with the full certificate chain included.
Place the certificate in the shibd directory toghether with the shibboleth2.xml, attribute-map.xml, etc.
Your AAI federation should provide you with Federation Metadata. The federation metadata contains information about all Service Providers and Identity Providers participating in the federation. The metadata provider URL is specified in shibboleth2.xml. The shibd is dowloading a backup matadata file locally.
Naturally, your OLAT Service Provider must also be included into your Federation Metadata.
You should check with your Identity Provider that the OLAT required attributes are visible to your OLAT Service Provider.
The last piece of the Shibboleth puzzle is the OLAT authentication provider. This must be specified in olat_config.xml, see AuthProvider of the LoginModule. There are 2 available authentication providers for Shibboleth: org.olat.shibboleth.DefaultShibbolethAuthenticationController where WAYF (see below) is activated over shibd config, and the org.olat.shibboleth.ShibbolethAuthenticationController which is used by UZH with SWITCH Embedded WAYF.
The EmbeddedWAYF or Embedded Discovery Service is specific to the SWITCH AAI. In a federated environment, the user has to declare where he wants to authenticate. The easiest way is to ask the user "Where Are You From?". The ideea is to embed WAYF on Resource (OLAT), customize look and feel but effectively still transparently use central WAYF. More info here.
The EMBEDDED-WAYF section in shibbolethlogin.html was automatically generated via the Embedded WAYF Code generator. It provides look and feel configurator, IdP list configurator, uses the same URL for all embedded WAYFs, the logic script is generated and loaded from the central WAYF. If you belong to the SWITCH AAI federation, all you have to do is to configure the Embedded DS in shibbolethlogin.html: configure layout, IdP list, and the different URLs (e.g. wayfSPEntityID) in src/serviceconfig/org/olat/shibboleth/_spring/olatdefaultconfig.xml. See Embedded DS SWITCH tutorial.
Suppose that all the above are fulfilled (that is the shibd is up and running an properly configured, the OLAT is shibboleth.enabled and running) it is time to check if shibboleth authentication works. Set the loglevel for the org.olat.shibboleth.ShibbolethDispatcher to DEBUG (into Administration/loglevels), now you should be able to see in olat.log the "Shib attribute Map", that is the attributes an authenticated user receives fom the Identity provider and provides via the service provider to OLAT.