UK Federation Information Centre | Documents / SetupSP browse

Configuring a Shibboleth Service Provider for the UK Federation

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">

Finally, 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 SCS:

 <CAPath>.../apache/conf/ssl.crt/sureserverEDU.pem</CAPath>

Downloading sureserverEDU.pem is described under CA Certificate at the end of GetSCSCert.

For GlobalSign:

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

The gs_organization_ca.crt file is the GlobalSign OrganizationSSL intermediate CA certificate downloaded when you obtained your certificate (see Root Certificates at the end of the GetGlobalSignCert page).

For the UK e-Science CA:

 <CAPath>.../apache/conf/ssl.crt/escience-ca.pem</CAPath>
 <CAPath>.../apache/conf/ssl.crt/escience-root.pem</CAPath>

The escience-ca.pem and escience-root.pem files are the required root and intermediate CA certificates, downloaded as described in the CA Certificates section at the end of GetUKeSciCert.

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 Apache

If you are using SSL for the target web site and you want to use the same certificate as for Shibboleth (not necessary but usual), the SSL configuration part of Apache's httpd.conf (or the SSL config file ssl.conf) should contain:

 
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 SCS certificates, the chain is just the sureserverEDU.pem intermediate CA certificate (see CA Certificate at the end of GetSCSCert for downloading instructions):

 SSLCertificateChainFile path/to/sureserverEDU.pem

For GlobalSign OrganizationSSL certificates, the chain is the gs_organization_ca.crt file downloaded as described at Root Certificate at the end of GetGlobalSignCert:

 SSLCertificateChainFile path/to/gs_organization_ca.crt

For Thawte certificates, again the chain is just the CA root certificate previously extracted from the zip file downloaded from http://www.thawte.com/roots/:

 SSLCertificateChainFile path/to/ThawtePremiumServerCA.txt

For UK e-Science certificates, the chain is the concatenation of the two CA certificates downloaded when you obtained your certificate: escience-ca.pem and escience-root.pem (see CA Certificates at the end of GetUKeSciCert). So first:

 cat escience-root.pem escience-ca.pem > escience.chain

Then in your Apache configuration:

 SSLCertificateChainFile path/to/escience.chain

For VeriSign certificates:

 SSLCertificateChainFile path/to/VeriSignClass3SecureServerCA.crt

Downloading VeriSignClass3SecureServerCA.crt was described earlier.

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.