How to Set Up a Shibboleth 2.X Service Provider on Linux and Apache

This document is for U-M information technology staff members. It provides basic installation instructions for Shibboleth 2.X Service Provider (SP) software on a Linux server with Apache version 2.2+ and explains how to configure it for the U-M Identity Provider (IdP).

Basic familiarity with Linux and Apache systems administration is assumed. If there is no RPM or binary available for your Linux distribution, you will need to know how to build and install standard Linux products. Configuring the software requires the ability to read and edit XML files with a text editor.

Server Preparation and Installation

1. Acquire a server.

2. Open firewall ports, if needed. Ports 80 and 443 must be open to inbound traffic, and 8443 must be open for outbound traffic.

3. Currently supported distributions of Linux are listed on the Linux Install page of the Shibboleth Project site. Be aware of the Shibboleth warning regarding SELinux.

4. The supported distributions of Linux can be installed from RPM via Yum. Installation instructions are also provided to build from SRPM or to build from Source, but doing so is not recommended.

5. The installation will build and install an apache module and the shibd daemon.

1. Verify Installation

Before configuring your server, verify that Shibboleth has been properly installed on your server.

1. Confirm Shibboleth functionality:

   sudo shibd -t

   Which should return a response that ends with:

   overall configuration is loadable, check console for non-fatal problems

2. Confirm Apache functionality:

   sudo apache2ctl configtest

   Which should return a response of:

   Syntax OK

3. Confirm shibd functionality:

   Restart the web server, then navigate to https://sp.example.org/Shibboleth.sso/Session replacing sp.example.org with the domain name of your Service Provider (SP).

   This should return a page response of:

   A valid session was not found.

   This message means that Shibboleth has been loaded by the web server and is successfully communicating with the shibd process.

2. Set Up Federation Files and Metadata

Shibboleth Service Provider Resources has links to the InCommon Federation metadata and certificate, as well as the U-M metadata and certificate. These resources are essential for configuring your installation, so it is a good idea to have both that document and this one open at the same time.

• Save the InCommon certificate to the following filepath:
  /etc/shibboleth/inc-md-cert.pem

• Save the U-M certificate to the following filepath:
  /etc/shibbboleth/umwebCA.pem

• Important Your SP should refresh the metadata for U-M and InCommon at least daily. Daily metadata refresh helps protect users of your SP from phishing and spoofing. See the InCommon Federation page on Metadata Consumption for more.

3. Configuration

Update shibboleth2.xml File

The shibboleth2.xml file will need to be configured for your Service Provider (SP). The file comes with the Shibboleth SP software, and is located by default in /etc/shibboleth.

Refer to a sample shibboleth2.xml file with U-M specific comments, or follow these instructions to make the appropriate changes to the file to configure it for your SP.

Note Before making changes, save a copy of the original shibboleth2.xml file.

1. Update the entityID:

   In the ApplicationDefaults element, the entityID value should be updated from entityID=”sp.example.org” to the host name, or a static identifier of your website. The entity ID does not need to resolve to a webpage.

   In the SessionInitiator element within the ApplicationDefaults element, the entityID there should be updated to the U-M entity ID. The entity IDs for the staging and production environments are different.

2. Update the support contact:

   • In the Errors element, update the supportContact value to a valid email address for the person managing the SP configuration. This email address is used by the Identity and Access Management (IAM) team to communicate any changes made to the SP owners.

3. Update the U-M metadata provider:

   Update the MetadataProvider element (as there are several) by changing the uri value to the U-M metadata. The metadata address is different for staging and production, so be sure to update it to the appropriate value. Until you have tested, use the staging value.

   Within the MetadataProvider element, locate the MetadataFilter certificate value, and update the certificate to the umwebCA.pem certificate.

4. Update the Federation metadata provider:

   If your SP will also be available to a federation such as InCommon, update a second MetadataProvider element by changing the uri value to the InCommon federation metadata.

   Within the MetadataProvider element, locate the MetadataFilter certificate value, and update the certificate to inc-md-cert.pem.

5. Save shibboleth2.xml.

Modify httpd.conf

Modify httpd.conf to protect your website. The configuration file is located by default at /etc/sysconfig/httpd.

1. Set the appropriate handler in Apache.

   <Location /Shibboleth.sso>
        SetHandler shib
   </Location>

2. Protect the appropriate content on your site.

   <Location /secure>
        AuthType shibboleth
        ShibtRequestSetting requireSession true
        Require valid-user
   </Location>

Install an X509 certificate

As Shibboleth requires a certificate and key to encrypt and decrypt attribute assertions, an X509 certificate must be installed for it to work. The Service Provider signing certificate (sp-cert.pem) and key (sp-key.pem) were generated in the installation process and do not need to be modified. They are located in the /conf/ directory.

Logging

Two different sets of Shibboleth-related log files are included with the installation.

1. shibd (shibd.log) logging is located in the /var/log/shibboleth directory and can be configured in the /etc/shibboleth/shibd.logger directory.

2. apache module (native.log) logging is located in the /var/log/httpd directory and can be configured in the /etc/shibboleth/native.logger directory.

Modify attribute-map.xml

Your SP’s attribute-map.xml file decodes the attributes released by the U-M Identity Provider (IdP). For more about U-M attribute releases, see U-M InCommon Shibboleth Attribute Release Policy and Procedure . The default Shibboleth SP configuration will not recognize some of the U-M-specific attributes such as uniqname, so the attribute-map.xml file needs to be modified.

Refer to a sample attribute-map.xml file with U-M specific comments, or see below for relevant excerpts from the file.

4. Register Service Provider

Generate SP metadata

Before registering your SP, you must generate your SP metadata:

1. Restart shibd:

   sudo service shibd stop
   sudo service shibd start

2. Download your metadata from the server:

   curl -o example.umich.edu-metadata.xml -k https://example.umich.edu/Shibboleth.sso/Metadata

   Where example.umich.edu is the entity ID of your SP configuration.

   Note -o specifies the appropriate filename, and -k ignores any SSL errors.

Contact U-M Identity and Access Management team

Once you have your SP metadata, submit the Shibboleth Configuration Request Form. The Identity and Access Management (IAM) team will contact you when you can begin testing.

Important If you make changes to your metadata at any time, you will need to provide the new version to the IAM team to be loaded into production.

5. Test Installation

Test SP configuration

Visit TestShib.org to set up and test your SP configuration to make sure that it works as expected.

Test SP integration with IdP

After the IAM team has contacted you and has added your metadata to the U-M staging IdP, you can test your SP to ensure it is properly integrated with the U-M IdP. Confirm that you are able to log in with your account or a test account, and that attributes are properly released.

1. Use the following commands in a protected document in the /secure directory of your SP, or the protected location you set.

   1. If server side includes (SSI) are enabled, use the following:

      <!--#printenv-->

   2. If PHP is enabled, use the following:

      <?php
      phpinfo();
      ?>

2. Using a web browser, visit the /secure directory (or other protected location) of your SP. You should be prompted to log in, and after logging in, you should see the attributes associated with the account that you used to log in to the secure directory.

3. If you are prompted to log in, your SP is properly integrated with the U-M staging IdP.

4. If the appropriate attributes are displayed, attributes are being properly released to your SP and that the attribute-map.xml file is properly configured.

Prepare for Production

After your SP passes testing: