Configuring a Shibboleth 1.3 Service Provider for the UK Federation

Please note that as Shibboleth 1.3 reached its end-of-life at the end of June 2010, we recommend that you install version 2 instead.

This description assumes you have already installed the Shibboleth 1.3 software, as described in the documentation at https://spaces.internet2.edu/display/SHIB/InstallingShibboleth

First, find the shibboleth.xml configuration file and go to that directory (usually etc/shibboleth under the Shibboleth installation directory).

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 < 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 UKFederationHelpdesk.)

Find the Shibboleth siterefresh executable file. Download (into the directory containing shibboleth.xml) the site metadata file ukfederation-metadata.xml and verify that it is signed correctly, as shown: 

 path/to/siterefresh --url http://metadata.ukfederation.org.uk/ukfederation-metadata.xml
   --out ukfederation-metadata.xml --cert ukfederation.pem

You must arrange to run this command regularly to keep the metadata up to date. This ensures that users attached to new UK federation Identity Providers will be able to access your services, and prevents access being granted to users attached to Identity Providers who have left the federation.

Editing shibboleth.xml

The Service Provider configuration file, shibboleth.xml, comprises one <SPConfig> element. The container elements within <SPConfig> are:

<Global>
No changes required
<Local>
Changes required
<Applications>
Changes required
<CredentialsProvider>
Changes required
<AttributeFactory>
No changes required

The changes you need to make to shibboleth.xml are identified below by reference to the XML container elements in which they occur.

In the <Local> 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 your own host name, e.g., shibbox.uni.ac.uk.

In the <Applications> element

Change the providerId attribute of the <Applications> element to the "Entity ID" value you gave when joining the UK Federation: 

 <Applications id="default"   
    providerId="https://yourdomain.ac.uk/shibboleth"
    homeURL="https://sp.example.org/index.html"
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

(The value of homeURL can be left unchanged.)

yourdomain.ac.uk is a placeholder, and needs to be replaced by the appropriate value. The value for providerId must match the "Entity ID" value which you gave when joining the UK Federation, and which is now embedded in your <EntityDescriptor> entry in the ukfederation-metadata.xml file.

________________________

Change the <SessionInitiator> element as follows:

Comment out (or remove) the default example: 

 
 <!-- This default example directs users to a specific IdP's SSO service. -->
 <SessionInitiator isDefault="true" id="example" Location="/WAYF/idp.example.org"
   Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
   wayfURL="https://idp.example.org/shibboleth-idp/SSO"
   wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

Find the InQueue example: 

 
 <!-- This example directs users to a specific federation's WAYF service. -->
 <SessionInitiator id="IQ" Location="/WAYF/InQueue"
   Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
   wayfURL="https://wayf.internet2.edu/InQueue/WAYF"
   wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

Replace it with this: 

 
 <SessionInitiator isDefault="true" id="UKFederation" Location="/WAYF/UKFederation"
    Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
    wayfURL="https://wayf.ukfederation.org.uk/WAYF"
    wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

________________________

In the <Errors> element, provide a suitable support contact email address: 

 supportContact="name@uni.ac.uk"

________________________

Within the <CredentialUse> element, add a <RelyingParty> element for the UK Federation: 

 <CredentialUse TLS="defcreds" Signing="defcreds">
     <!-- RelyingParty elements can customize credentials for specific
          IdPs/sets. -->
     <RelyingParty Name="http://ukfederation.org.uk"
       TLS="ukfederationCreds" Signing="ukfederationCreds"/>
 </CredentialUse>

________________________

Change the <MetadataProvider> element

Remove (or comment out): 

 
 <!-- Dummy metadata for private testing, delete for production deployments. -->
 <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
    uri="path/to/shibboleth-sp/etc/shibboleth/example-metadata.xml"/>

Change: 

 
  <!-- InQueue pilot federation, delete for production deployments. -->
  <MetadataProvider
    type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
    uri="path/to/shibboleth-sp/etc/shibboleth/IQ-metadata.xml"/>

to: 

 
 <MetadataProvider
    type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
    uri="path/to/shibboleth-sp/etc/shibboleth/ukfederation-metadata.xml"/>

________________________

If a <saml:Audience> element specifying 'urn:mace:inqueue' is present in the shibboleth.xml file: 

 <saml:Audience>urn:mace:inqueue</saml:Audience>

then delete this <saml:Audience> element line.

In the <CredentialsProvider> element

In the <Credentials> element, add a new <FileResolver> element defining the full path to the key and certificate files to use for the "ukfederationCreds" signing credential: 

 
<FileResolver Id="ukfederationCreds">
  <Key>
    <Path>.../apache/conf/ssl.key/shibbox.uni.ac.uk.key</Path>
  </Key>
  <Certificate>
    <Path>.../apache/conf/ssl.crt/shibbox.uni.ac.uk.crt</Path>
  </Certificate>
</FileResolver>

shibbox.uni.ac.uk.key is the key you generated when you requested a 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 must be given in the <Key> element: 

 <Key password="your password">

Certificates from Thawte are signed directly with the Thawte CA's root certificate and require nothing further in the <Certificate> element. However, other CAs use a chain of intermediate CAs in addition to the root. In those cases, you should add additional <CAPath> elements inside the <Certificate> element for the intermediate and root certificates. The exact form depends on which CA you used. The examples below assume certificate files are in Apache's ssl.crt directory, but you may put them anywhere.

For the JANET Certificate Service: 

 <CAPath>.../apache/conf/ssl.crt/JANET-intermediate-cert.pem</CAPath>

For further details, see CA Certificate at the end of GetJCSCert.

For VeriSign: 

 <CAPath>.../apache/conf/ssl.crt/VeriSignClass3SecureServerCA.crt</CAPath>

Downloading the VeriSignClass3SecureServerCA.crt intermediate CA certificate is described at the end of GetVeriSignCert (see CA Certificate).

That completes the editing of the shibboleth.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.

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 .../apache/conf/ssl.key/shibbox.uni.ac.uk.crt
SSLCertificateKeyFile .../apache/conf/ssl.crt/shibbox.uni.ac.uk.key

These are the same files previously referenced by the <FileResolver id="ukfederationCreds"> element in shibboleth.xml.

It is also desirable to configure Apache to send the certificate of the CA that signed the server certificate (and any 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 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.

Testing

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:

ProtectNetwork
TypeKey Bridge

Keeping Metadata Refreshed

As mentioned previously, the siterefresh command should be run as a regularly scheduled job to keep your site's locally cached copy of the federation metadata file, ukfederation-metadata.xml, up to date.

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.