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.
- Upgrading from a V2 SP
- Setting your SP's entityID
- Metadata from the UK federation
- IdP Discovery
- Configuration options for IIS webserver
- Next steps
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
You should upgrade the SP software using the same mechanism you installed it. For example, on a RedHat linux system you would typically
There are some configuration options you may need to edit. Please review our Upgrading from V2 page.
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
<ApplicationDefaults entityId="https://sp.uni.ac.uk/shibboleth" REMOTE_USER="eppn subject-id pairwise-id persistent-id"> ...
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
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 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
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
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.
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
<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
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
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.