SDSS Documentation Centre | Documents / SetupSP browse

Configuring a Shibboleth Service 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.xml configuration file and go to that directory (usually shibboleth/etc/shibboleth under the Shibboleth installation directory).

Download into that directory the certificate used to sign the SDSS metadata from http://sdss.ac.uk/fed/sdss.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 < sdss.pem

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, see http://edina.ac.uk/about/contact.html)

Find the Shibboleth siterefresh executable file. Download (into the directory containing shibboleth.xml) the site metadata file sdss-metadata.xml and verify that it is signed correctly, as shown:

 path/to/siterefresh --url http://sdss.ac.uk/fed/sdss-metadata.xml
   --out sdss-metadata.xml --cert sdss.pem

You must arrange to run this command regularly as a cron job to keep the metadata up to date. This ensures that users attached to new SDSS 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

<RequestMap> changes The values specified in the <RequestMap> element relate to the handling of requests to use a service protected by Shibboleth. This is described in https://spaces.internet2.edu/display/SHIB/SPProtectionConfig.

Within <RequestMap>, the <Host> element provided is an example:

 
<Host name="sp.example.org">
  <Path name="secure" authType="shibboleth" requireSession="true"/>
</Host>

This should be modified to suit your own circumstances.

In the <Applications> element

Change the providerId attribute of the <Applications> element to the URI (entityID) you gave when joining the SDSS 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 SDSS Federation, and which is now embedded in your <EntityDescriptor> entry in the sdss-metadata.xml file (see http://www.sdss.ac.uk/fed/sdss-metadata.xml).

________________________

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"/>

Replace 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"/>

with the following SDSS reference:

 
 <!-- This directs users to the SDSS federation's central WAYF service. -->
 <SessionInitiator isDefault="true" id="SDSS" Location="/WAYF/SDSS"
   Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
   wayfURL="https://wayf.sdss.ac.uk/shibboleth-wayf/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 SDSS Federation:

 
 <CredentialUse TLS="defcreds" Signing="defcreds">
    <!-- RelyingParty elements can customize credentials for specific
         IdPs/sets. -->
    <RelyingParty Name="urn:mace:ac.uk:sdss.ac.uk:federation:sdss"
      TLS="sdssCreds" Signing="sdssCreds"/>
 </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/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/etc/shibboleth/IQ-metadata.xml"/>

to:

 
<!-- SDSS federation. -->
  <MetadataProvider
    type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
    uri="path/to/shibboleth/etc/shibboleth/sdss-metadata.xml"/>

________________________

Change <saml:Audience> from the default urn:mace:inqueue to:

 <saml:Audience>urn:mace:ac.uk:sdss.ac.uk:federation:sdss</saml:Audience>

In the <CredentialsProvider> element

In the <Credentials> element, add a <FileResolver> element defining the key and certificate files to use for the "sdssCreds" signing credential:

 
<FileResolver Id="sdssCreds">
  <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 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="sdssCred"> 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 GlobalSign server certificates, this is the same secureroots_new.crt file described previously:

 
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, 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

Keeping Metadata Refreshed

Finally, as mentioned previously, the siterefresh command should be run as a regular cron job to keep your site's locally cached copy of the federation metadata file, sdss-metadata.xml, up to date.