Integrating Shibboleth Service Provider with Elements

If your institution uses Shibboleth and has an Identity Provider server set up, it is possible to leverage this to enable SAML Single Sign-On (SSO) for Elements. There are three main pieces involved in Elements Shibboleth integration.

1. The institution’s Shibboleth Identity Provider (IdP) server.

2. A Shibboleth Service Provider (SP) service installed on the Elements application server and integrated with the web server hosting Elements (IIS).

3. Elements itself.
   Specifically with the appropriate configuration of a Shibboleth Authentication Mechanism and the data provided as part of the HR feed.

When Shibboleth is being used to provide SSO for Elements it acts to protect access to Elements in such a way that Element’s own login page is almost never seen by an end user. Instead the user is taken to the institution’s IdP to login. To achieve this both Shibboleth and Elements need to be set up correctly:

• The Shibboleth SP must be configured so that it presents the “username” of the authenticated user to the Elements application in a known HTTP header.

• Elements must have a Shibboleth Authentication Mechanism set up to specify the name of the HTTP header being populated by Shibboleth.

• The institution must ensure that the data being provided in Elements’ HR feed is such that the user accounts within Elements have 'username' values matching the data being returned by Shibboleth and have “AuthenticatingAuthority” values matching the name of the Shibboleth Authentication Mechanism as it is configured within Elements (See Appendix A).

Note that a standard part of Elements operation is to redirect any requests that are not associated with a current Elements session to the Elements login page. Additionally (under normal configuration) it will redirect any requests for an unsecured (plain http) version of the login page to the equivalent secure (https) version. Therefore any attempts to access an Elements resource will have to first pass through the secure Elements login page.

When fully integrated Element’s Shibboleth integration works as follows:

• The SP service is configured to detect any web requests attempting to access the secure (https) Elements login page that are not currently associated with a Shibboleth session.

• The SP service intercepts these requests before they reach the Elements application and redirects the user to the IdP for authentication.

• The IdP authenticates the user and redirects the user back to the Elements login page.

• The SP detects that the request for the Elements login page is now associated with a valid Shibboleth session, so it contacts the IdP and securely retrieves the attributes (that describe the logged in user) that it is allowed access to.

• The SP processes its attribute-map, and based on that configuration injects the retrieved user attributes into named HTTP headers in the web request (as it is seen by the Elements application) and passes the modified web request for the login page on to the Elements application.

• The Elements' login page handler looks to see what 'authentication mechanisms' are configured in Elements. If there is a 'Shibboleth' mechanism set up, then that mechanism’s configuration will specify the name of the HTTP header where it should look for the 'username' of the user authenticated by Shibboleth.

• If there is a value present in the configured header Elements compares the value against the usernames of all the user accounts within Elements that have an “AuthenticatingAuthority” property matching the “Shibboleth” Authentication Mechanism’s name. Assuming an appropriate user account with a matching username is found, then that account is logged in.

In order to use Shibboleth with Elements it is expected that the institution will:

• Ensure that Elements is installed and configured to be accessible via https (with a valid SSL certificate assigned to the DNS name being used to gain access to the server).

• Install the Shibboleth SP software into the default 'C:\opt' directory on the Elements Application server, using the appropriate version (x86 or x64), and set to 'Run as 32-bit' regardless of the architecture of the server the SP is being installed on.

• Complete the baseline configuration of the SP (Shibboleth2.xml) to enable it to talk to the institution’s IdP (including metadata exchange).

• Choose the appropriate Shibboleth attribute to be used as the user’s username (e.g. eppn or NetID).

• Ensure that this attribute is released to the SP from the IdP and configure the SP’s attribute-map to expose the selected attribute in a known HTTP header.

• Ensure that all Elements user accounts are using suitable values for their username (i.e. are using values that match the attribute being passed over from the IdP, and are unique).

• Ensure that all Elements user accounts use the same “AuthenticatingAuthority” value (and make note of the value in use).

Note these last two points will typically be achieved by editing the data being passed to Elements via the HR feed.

The following outlines the additional configurations that need to be made once the Prerequisites are in place.

• Login to Elements as an Elements' system administrator.

• Add a new Authenticating Authority (System Admin > Setup > Add Authenticating Authority).

• Set the new authenticating authority's name and display name. The 'Display name' can be anything, whereas the 'Authenticating authority' must match the same value as the “AuthenticatingAuthority” field in the HR feed of the institution's users.

• Select “Shibboleth 2” as the authentication method and enter the name of the HTTP header where the authenticated username will be made available to Elements.

Edit the Shibboleth.xml file to make Shibboleth protect the path “login.html” when it is accessed over https (see here). For example:

(note that these config settings are the minimum required and if you're experienced with configuring Shibboleth, you config may include extra attributes and/or differ from below. The examples below are to help guide those less experienced administrators)

<InProcess> section:

<Site id="1" name="sp.example.org" scheme="https" port="443"/>

<RequestMapper> section:

<Host name="sp.example.org" scheme="https" port="443" authType="shibboleth">
  <Path name="login.html" authType="shibboleth" requireSession="true"/>
</Host>

<ApplicationDefaults> section:

<ApplicationDefaults entityID="https://sp.example.org/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

<MetadataProvider type="XML" file="idp-metadata.xml"/>

<Sessions> section (withing Application Defaults section):

<SSO entityID="https://idp.example.org/idp/shibboleth"

Note that as we are using IIS the name “sp.example.org” should match the virtual host name assigned to the IIS site ID in the ISAPI section of the shibboleth.xml file (see here).

After making these changes ensure that you restart both the Shibboleth Windows Service and IIS.

Ensure that you have added an ISAPI filter to either the Server or the Site level node within IIS. The filter can be named anything (although we suggest simply “shibboleth”) but should reference the file located at : C:\opt\shibboleth\lib\shibboleth\isapi_shib.dll.

This ISAPI filter allows the Shibboleth Windows service to intercept requests to the Elements web server before they reach the main Elements application. Once this is in place you will not be able to easily access the Elements login page so do this step last and ensure that you have at least one Elements user account configured to login via shibboleth set up as an Elements system administrator.

Elements is capable of supporting different authentication protocols for different subsets of users (e.g. LDAP for one subset and Active Directory for another). This is achieved by configuring multiple “Authentication Mechanisms” within Elements each of which must have a unique name. Every user account created within Elements then has an “AuthenticatingAuthority” property which is simply a string value specifying the name of the mechanism that particular user should be logged in against.

When using Shibboleth this capability is not really useable as the normal Elements login page is no longer accessible. Nonetheless you must still create, and name, a “Shibboleth” authentication mechanism within Elements and ensure that all your user accounts “AuthenticatingAuthority” values reference the name of this mechanism (e.g. by amending your HR feed data appropriately).

• Detailed Installation Shibboleth Service Provider.pdf