Configuring a Shibboleth 2 Service Provider for the UK federation
The Shibboleth 2 SP went End of Life in July 2018. Please consider this page as legacy documentation
This description assumes you have downloaded and installed the current version of the Shibboleth 2.x SP software, and other supporting software, as described in the Shibboleth documentation, and tested its basic functionality using the testshib public access Shibboleth testing service.
The following configuration steps should be completed and the SP restarted before registering it in the federation; the configuration changes are reflected in the automatically-generated metadata, which is required for registration. The automatically-generated metadata can be found at:
where hostname is the fully qualified domain name of your SP server, eg. sp.example.com.
IdP discovery
The UK federation technical recommendations for participants document in section 6.2 recommends use of a local discovery service from which the user can select their identity provider. The service provider can configure such a discovery service to restrict the list of available identity providers to those that are known to subscribe to the service. The list might also be modified according to other properties such as geographical location or IP address.
A local discovery service can be implemented by deployment of custom code or of suitable discovery service software, such as the Shibboleth Embedded Discovery Service (EDS). For more information on the Shibboleth EDS please see the Shibboleth EDS documentation on the Shibboleth website.
Hide from Discovery
"Hidden" or "invisible" IdPs in the federation now carry the "Hide from Discovery" entity category, which enables the EDS and similar discovery service software to filter such IdPs out of the IdP list.
The particular configuration required for the Shibboleth EDS to filter out the hidden IdPs is in the SP configuration file. Once you have successfully installed the EDS, you can add the following DiscoveryFilter to your MetadataProvider element.
<DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true"
attributeName="http://macedir.org/entity-category"
attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
attributeValue="http://refeds.org/category/hide-from-discovery" />
See the Shibboleth SP MetadataProvider documentation for details.
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.
Editing shibboleth2.xml
Since the V2.4 release of the Shibboleth SP a simplified syntax has been available for configuring session initiation. The shibboleth2.xml file shipped with recent releases of the Shibboleth SP software uses that syntax; many SP operators can use this simplified syntax, which is covered in the <SSO> element section below.
However, you may have a requirement to use the SessionInitiator syntax, which is more flexible. This is covered in the <SessionInitiator > element section below. Please note that you must use the more complex version of shibboleth2.xml for this which is shipped in recent releases of the software as example-shibboleth2.xml; the shibboleth2.xml file in recent versions does not contain all the elements necessary to support the SessionInitiator syntax.
Configuration files from earlier V2.x versions of the Shibboleth SP are compatible with later versions.
The service provider configuration file, shibboleth2.xml, comprises one <SPConfig> element, and within that several container elements.
Edit shibboleth2.xml as follows:
The <InProcess> element (Microsoft IIS only)
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 Shibboleth SP IIS configuration page.
The <RequestMapper> element (Microsoft IIS only)
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 since V2.4 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.
The <ApplicationDefaults> element
Change the entityId attribute of the <ApplicationDefaults> element to the "Entity ID" value of your SP. Guidance on a suitable choice of value is given in the UK federation entity ID guidelines. Where the entity registrant does not own the domain name contained within the proposed Entity ID 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 persistent-id targeted-id">
...
The <SSO> element or the <SessionInitiator> element
You can use either the SSO syntax or the SessionInitiator syntax, but not both together. Please be aware that you need a different version of the shibboleth2.xml file depending on which syntax you plan to use. Please see the note about this in the editing shibboleth2.xml section above and in the two sub-sections below.
The <SSO> element
Use the default shibboleth2.xml file shipped in recent versions. If you are using the SSO syntax then you cannot also use the SessionInitiator syntax described below in the same file.
To configure the SP to authenticate with a particular IdP, edit the <SSO> element to include the IdP's entityID:
<SSO entityID="https://idp.uni.ac.uk/idp/shibboleth">
SAML2 SAML1
</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 SAML1 </SSO>
Putting SAML 2 first specifies that SAML 2 should be used in preference, ie. in operation with any IdP that supports it.
For other options please see the Shibboleth SP documentation on the <SSO> element.
As mentioned in the IdP discovery section above, the UK federation recommends that service providers deploy a local discovery service in preference to the UK federation CDS.
The <SessionInitiator> element
Use the example-shibboleth2.xml file shipped in recent versions (it will need to be renamed to shibboleth2.xml; take a back-up copy of the existing shibboleth2.xml file first in case you have a later requirement for the SSO syntax). If you are using the SessionInitiator syntax then you cannot also use the SSO syntax described above.
Insert a new <SessionInitiator> element into the <Sessions> element just before the 'Default example':
<SessionInitiator isDefault="true" id="UKfederation" type="Chaining" Location="/UKfederation"> <SessionInitiator type="SAML2" template="bindingTemplate.html"/> <SessionInitiator type="Shib1"/> <SessionInitiator type="SAMLDS" URL="https://wayf.ukfederation.org.uk/DS" /> />
Putting SAML 2 first specifies that SAML 2 should be used in preference, ie. in operation with any IdP that supports it.
For other options please see the Shibboleth SP documentation on the <SessionInitiator> element.
As mentioned in the IdP discovery section above, the UK federation recommends that service providers deploy a local discovery service in preference to the UK federation CDS.
The <Errors> element
In the <Errors> element, provide a suitable support contact email address:
supportContact="support@uni.ac.uk"
Note that this email address may appear in error pages generated by the SP.
The <MetadataProvider> element
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" uri="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"/> </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.
Trust fabric certificate
You will normally require two X.509 digital certificates, one for federation trust fabric purposes and one for browser-facing purposes, to protect the SSL AssertionConsumerService URLs of the SP. This section is concerned with the trust fabric certificate. The browser-facing certificate is considered in the next section.
Authenticating the trust fabric certificate
Whether you use a self-signed certificate or a CA certificate (see below), the UK federation will need to authenticate it. The support team will send an email to your registering Management Contact containing a one-time security string and specifying the certificate's SHA-256 fingerprint, asking them to agree to the inclusion of this particular certificate in the SP metadata registration. If you have OpenSSL installed you can obtain the SHA-256 fingerprint by running this command, from a Windows command line or a Unix shell:
openssl x509 -sha256 -fingerprint -noout -in sp-cert.pem
On Windows you can also obtain the fingerprint by taking a copy of sp-cert.pem and changing the .pem filename extension to .crt on the copy. Double-click the copy and choose the Details tab on the Certificate dialogue box that appears. Scroll to the bottom of the box containing the fields and values and choose Thumbprint. The certificate fingerprint (referred to here as the thumbprint) will appear in the box below.
Self-signed certificate (recommended)
The Shibboleth 2.x SP installation generates a self-signed certificate with a lifetime of 10 years and a 2048-bit key. These are named sp-cert.pem and sp-key.pem respectively, and are in the Shibboleth SP installation directory or folder. The UK federation recommends that you use this certificate for trust fabric purposes within the federation. If you decide to do so then you do not need to change anything here, and should proceed to the next section.
CA certificate (accepted but not recommended)
You may wish to use a CA certificate for the federation trust fabric instead of the self-signed certificate. The federation does not recommend this, but if you have a particular requirement for it then it will be accepted. Deployers frequently use the commercial browser-facing certificate that is required for protecting the SP endpoints.
If you are using a CA certificate then you will need to make the following changes. Note that the files referred to here are the same files referenced in the next section.
Find the two lines
<!-- Simple file-based resolver for using a single keypair. -->
<CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
Replace them with the following:
<!-- Simple file-based resolver for using a single keypair. -->
<CredentialResolver type="File" key="/path/to/sp.uni.ac.uk.key"
certificate="/path/to/sp.uni.ac.uk.crt"/>
sp.uni.ac.uk.key is the private key you generated when you requested the certificate. sp.uni.ac.uk.crt is the signed certificate file returned by the CA, corresponding to the key. The paths shown above assume that you put the files in the key and certificate directories conventionally used for Apache SSL. It is common practice to share certificates between Shibboleth and Apache in this way. If you encrypted the key, a password attribute must be added to the <Key> element:
<Key password="your password">
That completes the editing of the shibboleth2.xml file.
Reconfigure web server
A service provider's AssertionConsumerService (ACS) URLs are required by the UK federation to be https URLs. Your web server must therefore be configured to support SSL, and a commercial SSL certificate will be required to protect the ACS locations. The documentation here focuses on the essential configuration to enable SSL and protect with a certificate, but you should also follow recommended good security practice with respect to the SSL configuration. A useful SSL resource on the web is SSL Labs, which has an online tool for testing your SSL configuration.
You will also need to configure the web server to protect your content with appropriate authentication settings. For Apache please see the SP documentation for Apache on shibboleth.net; for IIS please see the SP documentation for IIS on shibboleth.net.
Configuring the browser-facing certificate
Using the Apache web server as an example, you need to add the following lines to the port 443 VirtualHost in the SSL configuration file (normally /etc/httpd/conf.d/ssl.conf).
SSLEngine on SSLCertificateFile .../path/to/sp.uni.ac.uk.crt SSLCertificateKeyFile .../path/to/sp.uni.ac.uk.key
Because the ACS Location URLs are seen by the user's browser, the certificate (and corresponding key) here needs to be the browser-facing certificate you obtained from a CA.
You should also configure Apache to send the intermediate certificate chain for the CA. If this certificate chain is not provided, the browser may not be able to verify the server certificate and may report an error to the user. The chain to use depends on which CA signed the certificate.
For Jisc Certificate Service certificates, the chain comprises the intermediate CA certificates which accompany your certificate in the zip file provided:
SSLCertificateChainFile path/to/Jisc-intermediate-cert-chain.pem
For other CAs, the chain of intermediate certificates required will be described in their documentation, and may differ depending on the exact type of certificate purchased.
Please note that you should not include the CA's root certificate in the certificate chain, because some SSL clients cannot verify the certificate chain if the root certificate is present.
Testing
Once you have completed the above configuration stages you will need to register the SP before you can test it within the UK federation. Ensure that you have restarted the SP before registration so that the configuration changes are reflected in the SP's automatically-generated metadata. The automatically-generated metadata can be found at:
where hostname is the fully qualified domain name of your SP server, eg. sp.example.com.
The UK federation now operates a test IdP that can be used for testing SP deployments. For more information please see the UK federation test IdP documentation page.
Attributes
You will need to determine which attributes your service requires to be released to it by IdPs. This will be at least partially determined by the nature of your web application software. Please see the Shibboleth SP attributes pages for more information about how your application can access and use attributes.
Please note that the federation strongly recommends that access to services be granted on the basis of the values and types of attributes released by IdPs to the SP. Access should not be granted on the basis of successful authentication alone.
Please see the attribute usage table and the text preceding it for details of the core attributes in use in the UK federation. Please also see the federation's Technical Recommendations for Participants, section 7, for a more detailed discussion of attributes, and in particular section 7.6 "Working Without Attributes" for an explanation of why the federation recommends authorisation on the basis of attribute values.
Once your service is operational
Once you have installed, configured and tested your service provider software, you need to tell potential users of any services that you intend to offer about the attributes that are required in order to gain access to the service. Details of the attributes required by your service should be documented on your service website. You can also have an informational page on the UK federation about your service; these pages are linked to from the UK federation services page. Please email the UK federation service desk if you would like your service to appear there.