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.

As the Shibboleth SP is security software, we strongly recommend that deployers sign up to the Shibboleth announce list to receive information about security issues and new releases.

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

Upgrading from a V2 SP

You should upgrade the SP software using the same mechanism you installed it. For example, on a RedHat linux system you would typically yum update.

There are some configuration options you may need to edit. Please review our Upgrading from V2 page.

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

The typical way that SPs obtain metadata from the UK federation is to consume the UK federation metadata aggregate. To configure this, 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

Some categories of SPs can significantly reduce their memory usage by consuming metadata from our MDQ (metadata query) service. If your SP offloads IdP discovery to a third party service, or if it interacts with only a small number of IdPs, you may be able to use MDQ. Please contact the UK federation helpdesk for detailed advice.

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>

Alternatively, if you want to re-direct people to a discovery service (either your own local setup or one outsourced from a third party) so that they can choose their own IdP, the <SSO> element will need to include both discoveryProtocol="SAMLDS" and a discoveryURL pointing to an appropriate service (see the SP section of our IdP Discovery page). 

 <SSO discoveryProtocol="SAMLDS" discoveryURL="https://discovery.example.org/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