Sample U-M Shibboleth SP Configuration

This repository contains example configuration files for Shibboleth SPs at U-M.

Basic Configuration

There are a few basic steps required to configure an SP:

1. Set the Default EntityID
2. Choose IdP
3. Configure Error Handling
4. Generate SP Key and Certificate
5. Configure Access Controls

Set the Default EntityID

Set your default (or only) EntityID in /etc/shibboleth/shibboleth2.xml by replacing webapp.umich.edu in the entityID attribute on the ApplicationDefaults element with your hostname (or the loadbalanced name if you have multiple web servers for your application)

  <ApplicationDefaults
    entityID="https://webapp.umich.edu/"
    REMOTE_USER="uid eppn">

Choose IdP

All the configurations contain a shibboleth2.xml file with all the U-M IdPs commented out. You'll need to uncomment two definitions: one SSO element and one MetadataProvider element. Make sure you uncomment matching definitions. E.g. to use the production IdP, you would uncomment

  <!-- production IdP -->
  <SSO entityID="https://shibboleth.umich.edu/">SAML2</SSO>

and

  <!-- production IdP -->
  <MetadataProvider
    type="XML"
    url="https://shibboleth.umich.edu/md/umich-prod-idps.xml"
    backingFilePath="/var/cache/shibboleth/idp-metata.xml"
    reloadInterval="7200" />

Configure Error Handling

Update the attributes on the Error element with appropriate values:

  <Errors
    supportContact="YOUR-TEAM@umich.edu"
    helpLocation="https://its.umich.edu/help"
    styleSheet="/shibboleth-sp/main.css"/>

Generate SP Key and Certificate

Every SP should have an X.509 (SSL) key and certificate pair. These are used for signing authentication requests (optional) and decrypting encrypted assertions from the IdP (highly recommended). The key and certificate should not be the same key and certificate used by Apache. A self-signed certificate will be generated during the Shibboleth installation on most platforms, but it will probably have a very short lifetime. Generate a longer-lived self-signed certificate and use that instead. Assuming you are using one of the sample configurations, the key should be /etc/shibboleth/sp-key.pem and the certificate should be /etc/shibboleth/sp-cert.pem. If the hostname command returns the correct name for your host, run the following as root:

  # openssl req -x509 -nodes -days 3650 -newkey rsa:2048
  > -keyout /etc/shibboleth/sp-key.pem -out /etc/shibboleth/sp-cert.pem \
  > -subj /CN=`hostname`
  Generating a 2048 bit RSA private key
  .................................+++
  ...............................................................................+++
  writing new private key to 'sp-key.pem'
  -----

This will create a 2048 bit RSA private key (with no passphrase), and a self-signed certificate that is valid for almost 10 years (3,650 days) with the common name (CN) of the certificate subject set to your hostname. If hostname does not return the correct name for your host, just replace hostname with your hostname.

If you are running a cluster of Apache servers for your application, copy the key and certificate to each of the servers. DO NOT GENERATE A NEW KEY AND CERTIFICATE ON EACH CLUSTER MEMBER

Configure Access Controls

Use the examples in webapp-ssl.conf to define access controls for your site. You can also use .htaccess files in specific directories files if needed, but you'll have to allow AuthConfig overrides in the Apache configuration.

Metadata Configuration

Metadata is specific to each EntityID; generic metadata can be retrieved from the Shibboleth Handler for each EntityID by combining the virtual host HTTPS URL, the value of the handlerURL attribute on the corresponding ApplicationOverride element in shibboleth2.xml, and appending "/Metadata". For example, for the default EntityID on webapp.itlab.umich.edu, with the handler at /Shibboleth.sso we would use:

  % curl -so my-metadata.xml https://webapp.umich.edu/Shibboleth.sso/Metadata
  % grep entityID my-metadata.xml
  <md:EntityDescriptor ... entityID="https://webapp.umich.edu/">

Metadata Cleanup

Before you submit your metadata, clean up the metadata:

1. Remove the warning from the top of the file
2. Clean up the DigestMethod and SigningMethod elements - you can remove any that refer to sha1
3. Add contact information to the end of the metadata:

  <md:EntityDescriptor entityID="...">
    <md:SPSSODescriptor>
    <!-- -->
    </md:SPSSODescriptor>
    <md:Organization>
      <md:OrganizationName xml:lang="en">University of Michigan</md:OrganizationName>
      <md:OrganizationDisplayName xml:lang="en">University of Michigan</md:OrganizationDisplayName>
      <md:OrganizationURL xml:lang="en">http://www.umich.edu/</md:OrganizationURL>
    </md:Organization>
    <md:ContactPerson contactType="administrative">
      <md:GivenName>Babs Jensen</md:GivenName>
      <md:EmailAddress>bjensen@umich.edu</md:EmailAddress>
    </md:ContactPerson>
    <md:ContactPerson contactType="technical">
      <md:GivenName>Joe User</md:GivenName>
      <md:EmailAddress>joeuser@umich.edu</md:EmailAddress>
    </md:ContactPerson>
  </md:EntityDescriptor>

Submit Metadata and Request Attributes

Submit your cleaned up metadata via the Shibboleth Configuration Request Form, then submit the Shibboleth Attribute Release Request Form to get the attributes your application needs (if the default attributes are not enough).

When to Restart Apache and Shibd

If you only modify the Apache configuration, you only need to restart Apache.

If you modify the Shibboleth configuration, you need to restart Apache and shibd:

  # service apache2 restart ; service shibd restart