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.
