Configuring a Shibboleth V3 Service Provider for the UK federation

This page discusses how to configure the V3 SP software for use in the UK federation.

Prerequisites

Reference material for the Shibboleth V3 SP is found on the Shibboleth wiki.

All web service endpoints in the UK federation must be HTTPS-protected so we assume that you have already obtained and configured a browser-facing certificate from a certificate issuer such as the Jisc Certificate Service, a commercial certificate authority (CA) or Let's Encrypt. A useful resource on the web for good practice in configuring TLS deployments is SSL Labs, which has an online tool for testing your SSL configuration.

We assume that you have already installed the Shibboleth software according to the instructions on the Shibboleth wiki and have been able to complete the initial testing to find your SP's status at

https://localhost/Shibboleth.sso/Status

Setting your SP's entityID

Change the entityId attribute of the ApplicationDefaults element to the entityID value of your SP. Guidance on a suitable choice of value is given in the UK federation entityID policy. Where the entity registrant does not own the domain name contained within the proposed entityID value, the considerations described in the UK federation SP outsourcing page apply.

So, if your SP entity ID is https://sp.uni.ac.uk/shibboleth:

 <ApplicationDefaults entityId="https://sp.uni.ac.uk/shibboleth"
                       REMOTE_USER="eppn subject-id pairwise-id persistent-id">
    ...

Metadata from the UK federation

The UK federation signing certificate

First, find the Shibboleth installation directory containing the shibboleth2.xml configuration file and go to that directory. On Linux or Unix this is usually /etc/shibboleth, on Windows this is usually C:\opt\shibboleth-sp\etc\shibboleth.

Download into that directory the certificate used to sign the UK federation metadata ukfederation.pem. The file may be downloaded either via a browser (in which case users of Internet Explorer or Edge should ensure that they "view source" before cutting and pasting so as not to lose linebreaks) or via the command line.

  • Linux/Unix users should use
 curl -o /etc/shibboleth/ukfederation.pem http://metadata.ukfederation.org.uk/ukfederation.pem
  • Windows (PowerShell) users should use
 iwr -outf C:\opt\shibboleth-sp\etc\shibboleth\ukfederation.pem http://metadata.ukfederation.org.uk/ukfederation.pem

To ensure that the copy you have has not been tampered with, you should verify the SHA-256 fingerprint of the certificate. To determine the fingerprint of your copy of the certificate, run this openssl command:

 openssl x509 -sha256 -fingerprint -noout -in ukfederation.pem

You should then compare this with the correct fingerprint value, which can be obtained from a member of the UK federation team by phoning the federation helpdesk. We recommend a phone call, as it provides a higher level of assurance than email.

Configuring the SP to consume metadata from the UK federation

Find the line

  <MetadataProvider type="XML">

and remove the comments before that line and after the closing </MetadataProvider> tag. Edit the code so it reads as follows, only make the backingFilePath value specify the location of the Shibboleth SP configuration files:

 <MetadataProvider type="XML" url="http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
         backingFilePath="/path/to/ukfederation-metadata.xml" reloadInterval="14400">
       <MetadataFilter type="RequireValidUntil" maxValidityInterval="2592000"/>
       <MetadataFilter type="Signature" certificate="ukfederation.pem" verifyBackup="false"/>
 </MetadataProvider>

This has the effect of refreshing your copy of the federation metadata every 4 hours. As a security measure, it also causes metadata to be rejected whose root element does not contain a validUntil attribute, or whose validity period exceeds 30 days.

Typical locations for the metadata file would be /etc/shibboleth/ukfederation-metadata.xml or /var/cache/shibboleth/ukfederation-metadata.xml

IdP discovery

There are instructions and commentary on our IdP Discovery page.

To configure the SP to authenticate with a single IdP (for example for testing), edit the <SSO> element to include the IdP's entityID:

 <SSO entityID="https://idp.uni.ac.uk/idp/shibboleth">
   SAML2
 </SSO>

Instead, if you want to re-direct people to the UK federation CDS (Central Discovery Service) so that they can choose their own IdP:

 <SSO discoveryProtocol="SAMLDS" discoveryURL="https://wayf.ukfederation.org.uk/DS">
   SAML2
 </SSO>

For other configuration options please see the Shibboleth SP documentation on the <SSO> element.

Configuration options for IIS webserver

The <InProcess> element

If you are integrating Shibboleth with Microsoft's IIS then you will need to edit the <InProcess> element so that the values of the attributes in the <Site> element(s) reflect the IIS site number and virtual host name. It is also advisable to include scheme="https" and port="443" to ensure proper redirect generation. For example:

 <Site id="1" name="sp.uni.ac.uk" scheme="https" port="443"/>

More information is available at the InProcess configuration page.

The <RequestMapper> element

Change the value of the name attribute in the Host element to your site's hostname:

 <Host name="sp.uni.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true"/>
 </Host>

This element has been removed from the configuration file for Apache-based systems because these deployments can rely entirely on Apache functionality for request mapping, while IIS provides no such capability. More information is available on the Shibboleth SP RequestMapper page.

Next steps