SDSS Documentation Centre | Documents / SetupIdentityProviderVsn13 browse

Configuring a Shibboleth vsn 1.3 Identity Provider for SDSS

This description assumes you have already installed the Shibboleth 1.3 software itself, as described in the deployment guides at https://spaces.internet2.edu/display/SHIB/InstallingShibboleth.

(If you have installed the Shibboleth vsn 1.2 Identity Provider software, refer to SetupIdentityProvider instead of the page you are currently looking at.)

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/share/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/share/shibboleth-idp, then download the site's metadata from http://www.sdss.ac.uk/fed/sdss-metadata.xml as sdss-metadata.xml and verify that it is signed correctly, as shown:

 $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 to keep your copy of the federation 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 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">

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 the <EntityDescriptor> entry in your sdss-metadata.xml file. 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 your 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:///usr/share/shibboleth-idp/etc/sdss-metadata.xml"/>

Within <IdPConfig>, 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" 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 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 Service Provider sites may rely on the eduPersonScopedAffiliation attribute, you must find the resolver.xml file for your origin (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 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 just restart Tomcat) to ensure the updated origin.xml and resolver.xml are in use.

Reconfigure Apache

Assuming that you decided to use SSL (https) as recommended for your Shibboleth handle server, 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

If you placed the SSO service 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 SSO service above. In more complicated cases, the SSO service 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 attribute requester client certificates:

 
SSLVerifyClient require
SSLVerifyDepth 3
SSLCACertificateFile path/to/sdss-ca-bundle.crt

The SSLVerifyDepth of 3 is required to handle SP attribute requester client 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 here.

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:

 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 scheduled job to keep your site's locally cached copy of the federation metadata (sdss-metadata.xml) up to date.