Configuring a Shibboleth 2 Service Provider for the UK Federation
This description assumes you have already installed the Shibboleth 2 service provider software, as described in the documentation at https://spaces.internet2.edu/display/SHIB2/Installation. The following configuration steps need to 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.
First, find the Shibboleth installation directory containing the shibboleth2.xml configuration file and go to that directory (usually /etc/shibboleth).
Download into that directory the certificate used to sign the UK federation metadata from ukfederation.pem. To avoid being spoofed into allowing access to fake identity providers, you should verify the fingerprint of the certificate like this:
openssl x509 -fingerprint -noout -in ukfederation.pem
The correct fingerprint value must be determined offline from a member of the UK federation team to guard against the possibility of this web site being compromised. (To contact the UK federation team please refer to the federation helpdesk.)
Upgrading the Shibboleth SP from 1.3 to 2.x
Please see this document for a guide to upgrading a Shibboleth SP from version 1.3 to 2.x.
Editing shibboleth2.xml
Please note that you need to start with the shibboleth2.xml file that comes with the Shibboleth SP distribution. Do not use the version of the file that is generated by testshib, as that is a very cut-down version which will result in reduced functionality.
The service provider configuration file, shibboleth2.xml, comprises one <SPConfig> element, and within that several container elements.
Edit shibboleth2.xml as follows:
In 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 and virtual host configuration. It is also advisable to include scheme="https" and port="443" to ensure proper redirect generation. For example:
<Site id="1" name="shibbox.uni.ac.uk" scheme="https" port="443"/>
More information is available at the Internet2 SP/IIS configuration page.
In the <RequestMapper> element
Within <RequestMap>, the <Host> element provided is only an example:
<Host name="sp.example.org">
<Path name="secure" authType="shibboleth" requireSession="true"/>
</Host>
You should change sp.example.org to the host name of your new service provider, e.g., shibbox.uni.ac.uk.
In 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 here. Where the entity registrant does not own the domain name contained within the proposed Entity ID value, the following considerations apply.
Change the homeURL attribute of the <ApplicationDefaults> element to specify the location a user should be sent to (i.e. the first page of the service) if none is already specified.
<ApplicationDefaults id="default" policyId="default"
entityId="https://yourdomain.ac.uk/shibboleth"
homeURL="https://yourdomain.ac.uk/shibboleth/index.html"
...
yourdomain.ac.uk is a placeholder, and needs to be replaced by the appropriate value.
In the <Sessions> element
Insert a new <SessionInitiator> element into the <Sessions> element just before the 'Default example':
<SessionInitiator isDefault="true" id="UKFederation" Location="/WAYF/UKFederation"
type="WAYF" defaultACSIndex="5"
URL="https://wayf.ukfederation.org.uk/WAYF"
/>
In the <Errors> element
In the <Errors> element, provide a suitable support contact email address:
supportContact="name@uni.ac.uk"
Note that this email address may appear in error pages generated by the SP.
In the <MetadataProvider> element
Change the <MetadataProvider> element
After the line
<MetadataProvider type="Chaining">
insert the following block:
<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"/> <SignatureMetadataFilter 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.
Certificate credentials
You will normally require two X.509 digital certificates, one for federation trust fabric purposes and one to protect the SSL AssertionConsumerService URLs of the SP. This section is concerned with the trust fabric certificate. The SSL certificate is considered in the next section, although in some circumstances you may wish to use the SSL certificate for trust fabric purposes also.
The Shibboleth 2.x SP installation generates a self-signed certificate, also in the Shibboleth installation directory. 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. When you submit your service provider registration to the federation the federation support team will need to verify the origin of the self-signed certificate by telephoning you at a publicly-advertised number and asking you to read out the SHA-1 fingerprint of the certificate.
You may wish to use a commercial CA certificate instead. The federation does not recommend this, but if you have a particular requirement for it then it will be accepted. In such circumstances it is normal to use the SSL certificate that is required for protecting the SP endpoints. A limited number of CA certificate products are qualified for use in the federation trust fabric; please see this page for the list. 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="sp-key.pem" certificate="sp-cert.pem"/> -->
<CredentialResolver type="File">
<Key>
<Path>.../path/to/shibbox.uni.ac.uk.key</Path>
</Key>
<Certificate>
<Path>.../path/to/shibbox.uni.ac.uk.crt</Path>
</Certificate>
</CredentialResolver>
shibbox.uni.ac.uk.key is the private key you generated when you requested the certificate. shibbox.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
Irrespective of whether or not you want to encrypt traffic to your application proper, a service provider's Assertion Consumer Service (ACS) Locations 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.
For example, in Apache 2.x you need to add the following lines to the SSL configuration file (normally /etc/httpd/conf.d/ssl.conf).
SSLEngine on SSLCertificateFile .../path/to/shibbox.uni.ac.uk.crt SSLCertificateKeyFile .../path/to/shibbox.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.
It is also desirable to configure Apache to send the certificate of the CA that signed the certificate (and any other intermediate CAs) to the client browser. 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 obviously depends on what CA signed the server certificate.
For JANET Certificate Service certificates, the chain comprises the intermediate CA certificates which accompanies your certificate in the zip file provided (see Submitting the Request at the end of GetJCSCert).
SSLCertificateChainFile path/to/JANET-intermediate-cert-chain.pem
For other CAs, the chain of intermediate certificates required (if any) will be described in their documentation for "how to configure your web server" and will often differ depending on the exact type of certificate purchased.
For other CAs, the chain of intermediate certificates required (if any) will be described in their documentation for "how to configure your web server" and will often differ depending on the exact type of certificate purchased.
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 UK federation does not operate a test IdP at present. However, if you have not deployed an IdP of your own for testing, you can create test accounts at one of the open-access IdPs within the federation. Currently these are:
Once your Service is Operational
Once you have successfully installed and configured your service provider software, you need to tell potential users of any services which you intend to offer what attributes are required in order to gain service. See the table in AttributeUsage and the text preceding it for details of how to do this. You may also wish to contact existing users individually.