Configuring a Shibboleth Identity Provider (Origin) for SDSS
This description applies to configuration of the Shibboleth 1.2 IdP software. It assumes that you have already installed the Shibboleth 1.2 software, as described in the deployment guides at http://www.switch.ch/aai/docs/shibboleth/internet2/1.2/deploy-guide-origin1.2.1.html. (If you have installed the Shibboleth 1.3 software, refer instead to SetupIdentityProviderVsn13.)
First, find the Shibboleth origin.xml file, which is usually in webapps/shibboleth/WEB-INF/classes/conf under the Tomcat installation directory.
Download into the directory containing origin.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 targets, 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 the $SHIB_HOME variable is set as described in the Shibboleth origin deployment guide, to the directory where the origin tar file was unpacked, typically /opt/shibboleth-origin-1.2, then download the sites metadata from http://www.sdss.ac.uk/fed/sdss-sites-12.xml as sdss-sites-12.xml and verify that it is signed correctly, as shown:
$SHIB_HOME/bin/metadatatool --in http://www.sdss.ac.uk/fed/sdss-sites-12.xml --keystore sdss.jks --alias sdss -o sdss-sites-12.xml
You must also arrange to run this command regularly as a cron job to keep 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.
Edit origin.xml as follows. Modify the AAUrl, defaultRelyingParty and providerId attributes of <ShibbolethOriginConfig> to:
<ShibbolethOriginConfig ... AAUrl="https://shibbox.uni.ac.uk/shibboleth/AA" defaultRelyingParty="urn:mace:ac.uk:sdss.ac.uk:federation:sdss" providerId="urn:mace:ac.uk:sdss.ac.uk:provider:identity:yourdomain.ac.uk">
The defaultRelyingParty is the URN of the federation, which is fixed. AAUrl and providerId must match the values you gave when joining, which are now embedded in your <OriginSite> entry in the sdss-sites-12.xml file.
Change the <FederationProvider> URI to refer to sdss-sites-12.xml:
<FederationProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadataLoadWrapper" uri="/conf/sdss-sites-12.xml"/>
Within <ShibbolethOriginConfig>, add a clause identifying the certificate to use when signing identity assertions for this federation:
<RelyingParty name="urn:mace:ac.uk:sdss.ac.uk:federation:sdss" signingCredential="sdssCred"> <HSNameFormat 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 format="PEM">
<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 and sent to the CA 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">
If you are using a GlobalSign certificate, you must add an extra line inside the <Certificate> element, after <Path>...</Path>:
<CAPath>file://.../apache/conf/ssl.crt/secureroots_new.crt</CAPath>
This refers to the chain of GlobalSign intermediate CA certificates downloaded when you obtained your certificate (see Root Certificates at the end of the GetGlobalSignCert page). You will need to copy this file to an appropriate directory (Apache's SSL certificate directory in the example above). A <CAPath> is not required for SDSS CA or Thawte certificates because they are issued directly by a root CA, with no chain of intermediate CAs.
Because SDSS target sites may rely on the eduPersonScopedAffiliation attribute, you must find the resolver.xml file for your origin (in the Tomcat webapps/shibboleth tree) 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 federation (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 just restart Tomcat) to ensure the updated origin.xml and resolver.xml are in use.
Reconfigure Apache
Assuming you decided to use SSL (https) as recommended for your Shibboleth handle server then ensure that the <VirtualHost> context for the handle server in Apache's httpd.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 .key are the same files discussed in <Credentials> above, and are usually placed in Apache's conf/ssl.crt and conf/ssl.key directories.
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:
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
If you placed the handle server and attribute authority in separate <VirtualHost> contexts then the same configuration setup has to be repeated in the <VirtualHost> for the attribute authority. In simple cases, the required configuration directives will be the same as for the handle server above. In more complicated cases, the handle server and attribute authority may need different certificates (see WhatCertificates).
For the attribute authority virtual host, you must additionally enable client certificate verification and set the list of trusted CAs that will be accepted as signers of client (SHAR) certificates:
SSLVerifyClient require SSLVerifyDepth 3 SSLCACertificateFile path/to/sdss-ca-bundle.crt
The SSLVerifyDepth of 3 is required to handle target (SHAR) certificates issued by GlobalSign (the default of 1 is sufficient for certificates issued by the SDSS CA). The sdss-ca-bundle.crt file can be downloaded from sdss-ca-bundle.crt.
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 origin site from the WAYF page 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:
https://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 cron job to keep your site's locally cached copies of the federation metadata (sdss-sites-12.xml) up to date.