Configuring a Shibboleth Identity Provider for SDSS
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 sdss.jks from http://www.sdss.ac.uk/fed/sdss.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 fingerprint of the certificate, like this:
keytool -list -keystore sdss.jks -alias sdss
You can 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 SDSS team to guard against the possibility of this web site being compromised. (To contact SDSS via the EDINA helpdesk, refer to http://edina.ac.uk/about/contact.html)
Ensure that the $IDP_HOME variable is set to the directory where the IdP tar file 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 http://www.sdss.ac.uk/fed/sdss-metadata.xml as sdss-metadata.xml and verify that it is signed correctly:
$IDP_HOME/bin/metadatatool --in http://www.sdss.ac.uk/fed/sdss-metadata.xml --keystore sdss.jks --alias sdss -o sdss-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/shibboleth-idp/AA" defaultRelyingParty="urn:mace:ac.uk:sdss.ac.uk:federation:sdss" providerId="https://yourdomain.ac.uk/shibboleth">
Note that 'shibbox.uni.ac.uk' and 'yourdomain.ac.uk' are placeholders, and need to be replaced by appropriate values. The defaultRelyingParty is the URN of the SDSS Federation, which is fixed. AAUrl and providerId must match the 'AA Location' and 'Entity ID' values respectively which you gave when joining the SDSS Federation, and which are now embedded in your <EntityDescriptor> entry in the sdss-metadata.xml file (see http://www.sdss.ac.uk/fed/sdss-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 the sdss-metadata.xml file, which is definitive.
Change the <MetadataProvider> URI to refer to sdss-metadata.xml:
<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadataLoadWrapper" uri="file://$IDP_HOME/etc/sdss-metadata.xml"/>
Within <IdPConfig>, modify the clause identifying the certificate to use when signing identity assertions for this Federation.
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, as specified below, to enable interoperability with older SPs.
<RelyingParty name="urn:mace:ac.uk:sdss.ac.uk:federation:sdss" signingCredential="sdssCred" schemaHack="true"> <NameID nameMapping="shm"/> </RelyingParty>
In the <Credentials> section, add a <FileResolver> clause defining the key and certificate files to use for the "sdssCred" signing credential:
<FileResolver Id="sdssCred">
<Key>
<Path>file://.../apache/conf/ssl.key/shibbox.uni.ac.uk.key</Path>
</Key>
<Certificate format="PEM">
<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 format="PEM" password="your password">
Finally, certificates from Thawte and the SDSS CA are signed directly with those CAs' root certificates 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 GlobalSign:
<CAPath>file://.../apache/conf/ssl.crt/secureroots_new.crt</CAPath>
The secureroots_new.crt file is the chain of GlobalSign intermediate CA certificates 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.
That completes the editing of the idp.xml file.
Editing resolver.xml
Because SDSS 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 SDSS 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 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.
For GlobalSign certificates, you can download the chain from http://support.globalsign.net/en/serversign/root_install_ap.cfm (follow the secureroots_new.crt link), then in httpd.conf (or ssl.conf):
SSLCertificateChainFile path/to/secureroots_new.crt
For certificates signed by the SDSS internal CA, the chain is just the CA root certificate, which can be downloaded from http://www.sdss.ac.uk/ca/sdss-ca.crt :
SSLCertificateChainFile path/to/sdss-ca.crt
For Thawte certificates, the chain is also 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
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 this SDSS test page:
https://target.sdss.ac.uk/secure/index.html
If you select your own IdP site from the WAYF page and then successfully authenticate, you should get to "Secured Page, You made it!"
Two other test pages list target CGI environment variables, thus showing attribute values:
http://nevis.ed.ac.uk:8885/cgi-bin/printenv http://target.iay.org.uk/secure/printenv.cgi
Other test pages are listed in the SDSS Federation Test Pages section of TechnicalDetails.
Keeping Metadata Refreshed
Finally, as mentioned previously, metadatatool should be run as a regular scheduled job, perhaps daily, to keep your site's locally cached copy of the Federation metadata (sdss-metadata.xml) up to date.