Configuring a Shibboleth Identity 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 idp.xml file, which is usually in the Shibboleth installation directory's sub-directory "etc". E.g. C:\shibboleth-idp\etc or /usr/local/shibboleth-idp/etc/.
Download into the directory containing idp.xml the Java keystore from ukfederation.jks. This keystore contains the federation's signing certificate. To avoid being spoofed into releasing users' attributes to fake Service Providers, ideally you should verify the SHA1 fingerprint of the certificate, like this:
keytool -list -v -keystore ukfederation.jks -alias ukfederation
Just hit Enter when prompted for the keystore password. You will be warned that the keystore's integrity cannot be verified automatically: 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. The team can be contacted via the help desk.
Ensure that the $IDP_HOME variable is set to the directory where the IdP was unpacked, e.g. C:\shibboleth-idp or /usr/local/shibboleth-idp, then from the directory containing idp.xml use the metadatatool command as follows to download the federation metadata from ukfederation-metadata.xml and verify that it is signed correctly:
$IDP_HOME/bin/metadatatool
--in http://metadata.ukfederation.org.uk/ukfederation-metadata.xml
--keystore ukfederation.jks --alias ukfederation -o ukfederation-metadata.xml
You must also arrange to run this command regularly as a scheduled job, perhaps daily, to keep your copy of the metadata up to date. This ensures that your users are able to access new Service Providers joining the federation and prevents release of user attributes to Service Providers who have left the federation.
Editing idp.xml
Edit idp.xml as follows. Modify the AAUrl, defaultRelyingParty and providerId attributes of <IdPConfig> to:
<IdPConfig ... AAUrl="https://shibbox.uni.ac.uk:8443/shibboleth-idp/AA" defaultRelyingParty="http://ukfederation.org.uk" providerId="https://yourdomain.ac.uk/shibboleth">
Note that 'shibbox.uni.ac.uk:8443' and 'yourdomain.ac.uk' are placeholders, and need to be replaced by appropriate values. The AAUrl and providerId values must match the 'AA Location' and 'Entity ID' values respectively which you gave when joining the UK federation, and which are now embedded in your <EntityDescriptor> entry in ukfederation-metadata.xml. Note in particular that the above suggested value for providerId might not match the value you gave when you joined the federation: check the value in ukfederation-metadata.xml, which is definitive. The defaultRelyingParty is the URI of the UK federation, which is fixed.
Change the <MetadataProvider> URI (near the end of idp.xml) to refer to ukfederation-metadata.xml:
<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata" uri="file://.../shibboleth-idp/etc/ukfederation-metadata.xml"/>
Back near the top of the file, within the <IdPConfig> element, modify the clause identifying the certificate to use when signing identity assertions for this federation:
<RelyingParty name="http://ukfederation.org.uk" signingCredential="ukfederationCred" schemaHack="true"> <NameID nameMapping="shm"/> </RelyingParty>
Note on schemaHack="true": Early versions of the Shibboleth SP rely on an XML parser that has significant bugs. Prior to Shibboleth 1.3, all versions of the IdP accommodated these bugs directly. From release 1.3 onwards, however, deployers must specifically add the attribute schemaHack="true" if they expect to be issuing attributes to older SP versions. It is recommended that this attribute be added, to enable interoperability with older SPs.
<Logging> <ErrorLog level="WARN" location="..." /> ... </Logging>
While you are just starting out, or trying to resolve a problem, it may be useful to change WARN to DEBUG in the <ErrorLog> element (shown above). Specifying DEBUG causes the log file produced to be more comprehensive and informative, but much larger.
In the <Credentials> section, add a <FileResolver> clause defining the key and certificate files to use for the "ukfederationCred" signing credential:
<FileResolver Id="ukfederationCred">
<Key>
<Path>file://.../apache/conf/ssl.key/shibbox.uni.ac.uk.key</Path>
</Key>
<Certificate>
<Path>file://.../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 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>file://.../apache/conf/ssl.crt/sureserverEDU.pem</CAPath>
Downloading sureserverEDU.pem is described under CA Certificate at the end of GetSCSCert.
For GlobalSign:
<CAPath>file://.../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>file://.../apache/conf/ssl.crt/escience-ca.pem</CAPath> <CAPath>file://.../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>file://.../apache/conf/ssl.crt/VeriSignClass3SecureServerCA.crt</CAPath>
Downloading VeriSignClass3SecureServerCA.crt is described at GetVeriSignCert (see CA Certificate).
That completes the editing of the idp.xml file.
Editing resolver.xml
Because UK Federation Service Provider sites may rely on the eduPersonScopedAffiliation attribute, you must find the resolver.xml file for your IdP (in $IDP_HOME/etc) and edit it as follows. Uncomment the <SimpleAttributeDefinition> for eduPersonScopedAffiliation and change smartScope="shibdev.edu" to one of the domains you specified when applying to join the UK Federation (of the form uni.ac.uk for an institution, shibbox.uni.ac.uk for a test machine, etc.). For example:
<SimpleAttributeDefinition
id="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
smartScope="shibbox.uni.ac.uk">
<AttributeDependency
requires="urn:mace:dir:attribute-def:eduPersonAffiliation"/>
</SimpleAttributeDefinition>
Restart the /shibboleth-idp web application (or restart Tomcat) to ensure the updated idp.xml and resolver.xml are in use.
Reconfigure Apache
Assuming that you decided to use SSL (https) as recommended for your Shibboleth SSO service, ensure that the <VirtualHost> context for the SSO service in the Apache config file httpd.conf (or the SSL config file ssl.conf) contains:
SSLEngine on SSLCertificateFile path/to/shibbox.uni.ac.uk.crt SSLCertificateKeyFile path/to/shibbox.uni.ac.uk.key
shibbox.uni.ac.uk.crt and shibbox.uni.ac.uk.key are the same files as discussed in <Credentials> above, and are usually placed in Apache's conf/ssl.crt and conf/ssl.key directories respectively.
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 obviously depends on what CA signed the server certificate. Modify httpd.conf (or ssl.conf) as shown in the examples below.
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 consists of a single intermediate CA certificate, gs_organization_ca.crt, which is downloaded as described under Root Certificates at the end of GetGlobalSignCert:
SSLCertificateChainFile path/to/gs_organization_ca.crt
For Thawte certificates, the chain is just the CA root certificate. A zip file of root certificates can be downloaded from http://www.thawte.com/roots/. You need ThawtePremiumServerCA.txt, which can be extracted from the Thawte Server Roots folder of the zip file, then:
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, the chain is just the VeriSignClass3SecureServerCA.crt intermediate CA certificate downloaded earlier:
SSLCertificateChainFile path/to/VeriSignClass3SecureServerCA.crt
Attribute Authority VirtualHost
If you placed the SSO service and attribute authority in separate Apache <VirtualHost> contexts then the same configuration setup as described above has to be repeated in the <VirtualHost> for the attribute authority. In most cases, the required configuration directives will be the same as for the SSO service.
For the attribute authority virtual host, you must additionally enable client certificate verification:
SSLVerifyClient optional_no_ca SSLVerifyDepth 10 SSLOptions +StdEnvVars +ExportCertData
Finally, you will need to restart Apache.
Testing
Once you have reconfigured Shibboleth and Apache as described above, you can test your setup by going to one of the following UK Federation test pages, which display attributes received by the SP:
https://ledi.edina.ac.uk:8885/cgi-bin/printenv https://target.iay.org.uk/secure/printenv.cgi
Keeping Metadata Refreshed
As mentioned previously, metadatatool should be run as a regular scheduled job, perhaps daily, to keep your site's locally cached copy of the UK Federation metadata (ukfederation-metadata.xml) up to date.
Finally
Once your Identity Provider installation is in service, you might wish to contact those UK federation Service Providers with whom you have service agreements, to inform them that you now have an Identity Provider within the UK federation and wish your end users to be able to access services via that route.
The information you give an SP depends on how it confirms that your organisation is a valid licence holder: they might, for example, wish to know the Shibboleth scope(s) which you are asserting.