## 2.7. Enabling the Shibboleth login

Shibboleth is a standardized authentication and authorization mechanism. With Shibboleth, OLAT forwards a user to its Identity Provider (her university / company website) for authentication. The Home Organisation will (upon successfull authentication) take the user back to OLAT including an Authentication Statement which is verified by OLAT. Upon proper verification of this Authentication Statement the user is automatically logged in to OLAT.

The configuration of Shibboleth is mostly done via build.properties / olat_config.xml. The following parameters have to be set:

1. `EnableShibbolethLogins` (true/false): If set to "true" Shibboleth will be enabled on your installation.

2. `ProviderId` (String): A unique identification of your local installation.

3. `Metadata` (Path/URI): This is the file that contains the Home Organisations supported for your users to authenticate. The file is based on the Shibboleth 1.3 metadata file. The file can be either locally (relative path to web application root or absolute path) or remote (URI accessible via HTTP).

4. `AAP` (Path/URI): The file contains your Attribute Acceptance Policy (AAP). The file can be either locally (relative path to web application root or absolute path) or remote (URI accessible via HTTP). If you do not have a specific Attribute Acceptance Policy (i.e. you accept all attributes) you may also leave this empty.

5. `ReloadMaxRetries` (Integer): The number of times the watchdog should re-try to fetch the sites.xml file if previous attempts failed. A value of "0" means unlimitted retries.

6. `CheckCertificateValidity` (true/false): Wether to check if the certificate used to sign the AuthorizationStatement was issued by an recognised Certificate Authority as defined by the ssl-truststore parameter of opensaml.properties file. Use this, if you want to make sure that only Home Organisations which you trust are allowed to authenticate users.

7. `CheckIssuerIP` (true/false): If set to true, the IP of a user who is trying to authenticate will be checked when the Identity Provider returns it's authentication statement. Usually you should set this to true for security reasons. With some proxies who do not assign stateful IPs, access will be denied and you may disable this feature.

8. `Credentials / Keystore`: These are the credentials used to connect to the Attribute Authority to retrieve Shibboleth attributes upon successfull authentication. `Type` may be either PKCS12 or JKS.

9. `Credentials / Truststore`: These are the credentials of Identity Providers who you allow to authenticate users (i.e. your federation's certificates). `Type` may be either PKCS12 or JKS.

10. `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" />)

11. `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. "eduPersonEntitlement" reads easier as opposed to "urn:mace:dir:attribute-def:eduPersonEntitlement" (which is the attribute's actual name). See the olat_config.xml.in file for an example.

12. `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 "urn:mace:dir:attribute-def:givenName" would be mapped to the OLAT user profile's first name with the following statement:

        <FirstName>urn:mace:dir:attribute-def:givenName</FirstName>

    Valid mappings are: FirstName, LastName, EMail, InstitutionalName, InstitutionalEMail, InstitutionalUserIdentifier.

Some of these parameters can be configured through the build.properties file.

Step by step guide to enable shibboleth on your OLAT installation (Without set up of identiy provider).

1. Get a FQDN (DNS name) for your OLAT installation like: olat.earth.sky

2. 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.

3. Let the certificate request sign from a certificate authority

4. Download the signed certificate in the PEM format with the full certificate chain included.

5. Convert the certificate into a format that tomcat likes (PKCS12) using openssl.

6. Place the certificate in a directory tomcat can read and adjust the build.properties with the path and password phrase.

7. Your AAI foderation should provide you with Federation Metadata. The federation metadata contains information about all Service Providers and Identity Providers participating in the federation. Download the file and place it inside webapp/WEB-INF direcotry and adjust the path in the build.properties file.

8. If you intend to load attributes from the identiy provider you should make sure your have the rights to access them.

9. run the config-all task and restart OLAT.