Shibboleth Configuration Guide

Using Shibboleth at Duke provides a way for websites to authenticate users by their NetID. The following guide explains how to configure a Shibboleth Service Provider 1.3.x with Duke's Shibboleth Identity Provider 1.3.3 located at https://shib.oit.duke.edu.

Metadata File

Download the metadata (Right click and save as)

Installation and Webserver Configuration

Linux Installations
To install Shibboleth on a Linux machine, use the Shibboleth package available with yum. Use the following command: yum install shibboleth

Mac OS X Installations
Download binaries for OS X v10.3 here: http://macintosh.duke.edu/software/files/shibboleth-sp-1.3e-macosx-10.3.tar.gz
Download binaries for OS X v10.4 here: http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/mac/

Please visit the Shibboleth Website for information on installing Shibboleth for Mac OS X.

Windows/IIS Installation
1. Download and install lastest version of Shibboleth from http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/1.3.1/win32/ (shibboleth-sp-1.3.1-win32.msi). During the installation, you can choose the installation directory.
2. The installer will add an ISAPI filter and an sso extension.
3. Restart IIS.

If you get a "HTTP 405 - Resource not allowed" error after being redirected to your site from Webauth, make sure the .sso mapping to isapi_shib.dll is at the site level and not just the top level.

For more information: https://spaces.internet2.edu/display/SHIB/SPWindowsInstall

Other OS Installations
Please visit the Shibboleth Website for information on installing Shibboleth for your platform.

Specific installation instructions for other platforms will be added later.

Apache Configuration
1. Ensure that the ServerName directive is set properly.
2. In most cases, UseCanonicalName will not be set. This should be set to On.
3. Include either apache.config, apache2.config, or apache22.config located in your Shibboleth install directory. The location of resources that should be protected by Shibboleth can be added in these files.
4. You can also use .htaccess files. For instance:

   AuthType shibboleth
   ShibRequireSession On
   Require user netid1@duke.edu netid2@duke.edu

Shibboleth Configuration

shibboleth.xml
From the default shibboleth.xml file given with Shibboleth Service Provider 1.3.x, the following changes need to be made:
1. Host: Set the Host value to the hostname of your Service Provider. Ex. verthandi.oit.duke.edu. Within the Host element, add Path elements for each path that requires Shibboleth authentication.

   Example 1 - Protect entire host:
   <Host name="verthandi.oit.duke.edu" authType="shibboleth" requireSession="true"/>

   Example 2 - Protect just the "secure" path:
   <Host name="verthandi.oit.duke.edu">
     <Path name="secure" authType="shibboleth" requireSession="true"/>
   </Host>

2. providerId: Set the providerId attribute within the Applications element to https://<your hostname>/secure/. If your site is not using SSL, use http instead of https in the providerId.

3. homeURL: Set the homeURL attribute within the Applications element to the home address of your application

4. wayfURL: Locate the SessionInitiator that contains an isDefault attribute set to true. Modify the wayfURL within that SessionInitiator element to https://shib.oit.duke.edu/shibboleth-idp/SSO

5. supportContact: Update the supportContact attribute within the Errors element.

6. MetadataProvider: You may have one or two MetadataProvider elements depending on your Shibboleth SP release. If you have two MetadataProvider elements, you can remove one of them. Update the other to use duke-metadata.xml. You can download the metadata file here: Metadata (Right click and save as)

7. Audience: If you have an Audience element (depending on your Shibboleth SP release), remove the element.

8. Credentials: Locate the FileResolver with Id="defcreds". Set the Path for the key and certificate files. We recommend that you use a long-lived self-signed certificates even if you're using a commercial certificate for your Apache or IIS web server. You can create a self-signed certificate using openssl on one of the public Linux machines. For instance, to generate a 5-year certificate:

   ssh login2.oit.duke.edu
   openssl genrsa -out server.key 2048
   openssl req -new -x509 -nodes -days 1825 -key server.key -out server.crt

9. If you are using IIS, add site names and aliases in the ISAPI element.

AAP.xml
Modify AAP.xml to include any attributes that you are requesting. For more information: https://spaces.internet2.edu/display/SHIB/NewSPAttribute

Attributes being requested must be approved by Electronic Access Services. Send your request to websso-info@duke.edu.

Example 1 - Request for NetID
This example assumes you are requesting to receive the NetID of authenticated users. The URN that's used to store NetID values is urn:mace:dir:attribute-def:eduPersonPrincipalName. eduPersonPrincipalName is a scoped attribute meaning the value you receive will be <NetID Value>@duke.edu. You can add the following AttributeRule to AAP.xml to retrieve the scoped NetID using the REMOTE_USER header.

<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonPrincipalName" Scoped="true" Header="REMOTE_USER" Alias="user">
<AnySite>
  <Value Type="regexp">^[^@]+$</Value>
</AnySite>
</AttributeRule>

Example 2 - Request for DukeID
This example assumes you are requesting to receive the Duke Unique ID of authenticated users. The URN that's used to store DukeID values is urn:mace:duke.edu:idms:unique-id. Note that unlike eduPersonPrincipalName, unique-id is not a scoped attribute. You can add the following AttributeRule to AAP.xml to retrieve the DukeID using the HTTP_SHIB_DUKE_UNIQUE_ID header.

<AttributeRule Name="urn:mace:duke.edu:idms:unique-id" Header="Shib-Duke-Unique-Id" Alias="unique-id">
<AnySite>
  <AnyValue/>
</AnySite>
</AttributeRule>

Example 3 - Request for Affiliation
This example assumes you are requesting to receive the affiliation of authenticated users. The URN that's used to store affiliation values is urn:mace:dir:attribute-def:eduPersonScopedAffiliation. Note that like eduPersonPrincipalName, affiliation is a scoped attribute. You can add the following AttributeRule to AAP.xml to retrieve the affiliation using the HTTP_SHIB_EP_AFFILIATION header. There may already be a rule for eduPersonScopedAffiliation in your AAP.xml. Be sure to remove that.

<AttributeRule Name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" Scoped="true" CaseSensitive="false" Header="Shib-EP-Affiliation" Alias="affiliation">
<AnySite>
  <Value>FACULTY</Value>
  <Value>AFFILIATE</Value>
  <Value>STAFF</Value>
  <Value>ALUMNI</Value>
  <Value>EMERITUS</Value>
  <Value>STUDENT</Value>
</AnySite>
</AttributeRule>

Logout
To enable users to logout of your service provider, modify the SingleLogoutService element in shibboleth.xml to the following:

<md:SingleLogoutService Location="/Logout" Binding="urn:mace:shibboleth:sp:1.3:Logout" ResponseLocation="https://shib.oit.duke.edu/cgi-bin/logout.pl"/>

Then just redirect users to /Shibboleth.sso/Logout on your web server for them to logout. Note that this method of logging out will not work properly if you are using the InCommon federation.

Starting Shibboleth
For Unix installs, simply run <Shibboleth install location>/sbin/shibd -f & and then restart Apache. Once in production, you should start and stop shibd as a service. For example, with Linux, you could use 'service shibd start' to manually start it. And also use chkconfig to turn it on for future reboots.

For Windows/IIS, restart Shibboleth and IIS services.

Registering Your Shibboleth SP

You must register your Shibboleth SP. Send the following information to websso-info@duke.edu

1. providerId
2. Self-signed certificate
3. Assertion Consumer Service URL. Usually https://<your hostname>/Shibboleth.sso/SAML/POST. If your site is not using SSL, use http instead of https in the URL.
4. Does your site using HTTP, HTTPS or both?
5. Your Organization Name and URL
6. Contact name and email address.
7. Any requested attributes approved by Electronic Access Services.

Also, be sure to add yourself to the shib-announce and shib-discussion mailing lists. They are used to send important information regarding the Shibboleth Identity Provider that Service Provider owners need to be aware of.

Questions?

If you have any questions on how to install or configure Shibboleth, send an email to websso-info@duke.edu.