This guide is intended for systems administrators who will be installing and maintaining SAML/Shibboleth service provider software for an application (or set of co-located apps) at Harvard. The following basic skills are expected of the reader:
 

• Familiarity with the local operating system, including how to install software (on some UNIX systems, this may mean compiling packages from source code or using the ITS-provided package)
• Configuring the local web server (Apache, IIS, etc.)
• Basic understanding of SSL, including how to generate a key and CSR
• Basic understanding of XML documents

Please note that this guide only provides information on SAML 2.x, because that is what our Shibboleth identity provider supports.

The Process 

1. Determine which attributes your application needs in order to make authorization decisions about users. Please start by consulting the list of standard attributes for SAML/Shibboleth Applications at Harvard; if you find that you need attributes that are not on this list, please contact ithelp@harvard.edu.
2. Register your application, including specifying which attribute your app needs, Register your application, including specifying which attribute your app needs, .
3. Install and configure your web server and the Shibboleth service provider (SP) software. (This will likely take you the most amount of time and effort, but the information below will help you get started.)
4. For more details on how to access attributes from SAML assertion in your code, see this link in the Shibboleth wiki.

Assumptions

• You are using Apache version 2.2 or greater. If you are using an older version of Apache, you are strongly urged to upgrade before proceeding.
• You will use Shibboleth SP version 2.4 or greater.
• You are looking for basic installation and configuration instructions for a single website and application. (For more complex installations, please contact ithelp@harvard.edu.)
• If an RPM or binary for your OS is not readily available, you are able to make one from source.

Registering Your App with Harvard

Please note that this page covers only the basic technical aspects of setting up Shibboleth. Please remember that in order to test your app or have it use production IAM services, you'll also need to register your app using this form.

Download and Install Shibboleth

Download and installation instructions are available on the Shibboleth Project wiki's installation page. You'll need to follow the information in the section for Native Service Provider. Follow the instructions specific to your platform; available OS options are Linux, Mac OSX, Solaris, and Windows. When you're done installing Shibboleth, you'll have the shibd daemon and the mod_shib Apache module (if you use Apache) installed in your host environment.

Configure Shibboleth for the Harvard IdP (Pre-Production)

Now you need to configure your SP to work with the Harvard University identity provider (IdP). It is easiest to start with a simple configuration and migrate to more more complex configurations later.

Update shibboleth2.xml

The shibboleth2.xml file contains the basic Shibboleth SP configuration. This file is located in your main Shibboleth directory, and configures things such as what SSL certificate you are using, what resources Shibboleth should protect, and how your application identifies itself to the Shibboleth IdP. You can find this file here:

• Red Hat or Ubuntu Linux: /etc/shibboleth/shibboleth2.xml
• ITS Solaris systems: /var/local/etc/shibboleth/shibboleth2.xml
• Other UNIX systems: /opt/shibboleth-sp/etc/shibboleth/shibboleth2.xml
• Windows: c:\opt\shibboleth-sp\etc\shibboleth

Make the following changes to the shibboleth2.xml file:

• Find the ApplicationDefaults element and set the entityID (see below for more details)

• Find the Sessions element and modify it for lifetime and timeout (in the example below, session lifetime is set to 2 hours and timeout to 1 hour)

  <Sessions lifetime="7200" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="; path=/; secure; HttpOnly">

• Find the first SSO element and set it as shown below; this will configure SSO for the Harvard University stage, (pre-production) IdP

  <SSO entityID="https://stage.fed.huit.harvard.edu/idp/shibboleth">     SAML2 SAML1 </SSO>

• Download our stage IdP metadata (stage-idp-metadata.xml) and save it in the same directory as shibboleth2.xml

• In shibboleth2.xml, find the line that begins <MetadataProvider type="XML" and update it as follows:

  <MetadataProvider type="XML" file="stage-idp-metadata.xml" />

More Details on Entity ID

Harvard's IdP sends your application attributes about the authenticated user. For your SP to process the attributes correctly, it needs to know which ones it will be receiving. To specify these, edit the attributes-map.xml file and save it in the same location as shibboleth2.xml. You may also wish to filter or transform the attributes; you can do this via the attribute_policy.xml file. Both of these files are in the same directory as shibboleth2.xml, and they include examples of how to configure attributes and attribute policies, respectively.

Harvard's IdP currently releases only a limited number of attributes by default. You may uncomment additional attributes in the attributes-map.xml file; however, simply doing this does not mean that your SP will receive those additional attributes. Each IdP's configuration is exclusively responsible for the release of attributes to your SP, which is why you need to specify your attribute requirements as part of the application registration process for the Harvard IdP. The attribute-map.xml file only tells your SP which received attributes from IdP are to be passed to your application.

Generate Your SP's Metadata File

Configuration up to this point has been to make the Shibboleth SP run on your server. Next, information must be exchanged with Harvard's IdP so that the IdP and SP can communicate. To do this, the IdP needs a copy of your SP's metadata. You can use the metagen.sh tool (found in the same directory as shibboleth2.xml) to create the metadata file for your SP.

First, make sure you've chosen a good entity ID, and have the public key certificate for your SP ready. Next, execute the metagen.sh command (in a terminal window or shell) as follows:

./metagen.sh -c certificate_path -h domainNameOfYourSP -e entityIDForYour SP > metadata.xml

   

This will send the metadata to metadata.xml. You may then wish to edit this file to add contact information for your organization's technical and administrative support. (While these fields are optional, you'll need to add them if you want your SP to be listed in InCommon metadata.)

After creating/editing the metadata, restart your Apache and shibd services. At this point, you can download your SP's metadata from the server's website simply by visiting its URL (example: https://hostname.harvard.edu/Shibboleth.sso/Metadata, replacing hostname.harvard.edu with your site's domain). You may also download your metadata from the server's website using a command such as curl on Linux (again, replacing hostname.harvard.edu with your site's domain name):

curl -o mysp.harvard.edu/metadata.xml -k https://hostname.harvard.edu/Shibboleth.sso/Metadata

   

When you have generated a copy of your metadata file, please email it to ithelp@harvard.edu. Please note that if you make configuration changes to your entity ID, change your contact data in shibboleth2.xml, or change your key or certificates, you should regenerate your metadata file and send it to the IAM team again.

Getting or Using Metadata from Non-Harvard IDPs

The SP needs to have metadata from each IdP whose users you wish to serve. If the IdPs of interest to you are part of InCommon, you can simply enhance the SP's shibboleth2.xml configuration file to download fresh copies of the InCommon bundled metadata. Learn more about this process here.

 

You can also include metadata from IdPs that aren't part of InCommon by storing the IdP's metadata locally. This example shows metadata from a local file and from a federation:

 

<MetadataProvider type="Chaining">    

<MetadataProvider type="XML" path="partners.xml"/>    

<MetadataProvider type="XML" url="http:SomeFederation.org/metadata.xml" backingFilePath="fedmetadata.xml"/>

</MetadataProvider>

There are a number of options for getting, validating, and filtering metadata that might be of interest to you. See these pages on the Shibboleth wiki:

 

Certificates

An X.509 (SSL) certificate is required within SAML/Shibboleth. We recommend that you use a self-generated certificate and keypair. The key/certificate pair sp-key.pem and sp-cert.pem, in the conf directory, are generated by the installation process and are referred to in shibboleth2.xml's CredentialResolver. Depending on your configuration, there may be no need to change these files. However, you can also generate these files if needed using the keygen script that comes with the Shibboleth SP installation (available in the conf directory). Please note that the certificate you use with your SAML/Shibboleth software should be different than your SSL certificate.

Initiating Authentication: Sessions and Discovery

The first time a user tries to access a protected resource in your application (i.e. a resource under "/protectedarea" or whatever path you configure), the SP code needs to know where to send the authentication request. To determine this, it checks what you have set up in the shibboleth2.xml file. There are two primary possibilities:

• Only one IdP is configured in the <SSO> section of the file. In this case, the SP sends the SAML authentication request to that IdP, and the user will be served the IdP's login screen in order to proceed.    
• A discovery service has been configured in the <SSO> section. In this case, the SP temporarily hands over control to that discovery service, which prompts the user to select his or her home institution ("where are you from?") from a drop-down list or similar interface element. The discovery service then returns the entity ID of the chosen institution's IdP to the SP.  At this point, the SP sends the SAML authentication request to that IdP, and the user will be served the IdP's login screen in order to proceed. If the user successfully authenticates at his or her home institution, the IdP sends a SAML authentication response to the SP, containing an assertion that holds attributes about the user. 

Note that an additional option does not involve shibboleth2.xml configuration, but rather features links for users to click which contain the entity ID of the "proper" IdP in the form of a parameter. Here's an example illustrating the key elements: https://SPhostname.harvard.edu/Shibboleth.sso/Login?entityID=https:/TheRightSchool.edu/idp/shibboleth —

• https://SPhostname.harvard.edu/Shibboleth.sso/Login refers to the SP's default "initiate session" endpoint.
• entityID=https://TheRightSchool.edu/idp/shibboleth is the entity ID for the IdP of interest. Note that the SP needs to have metadata about this IdP; the SP will use the entity ID to look up information in the metadata (such as the IdP's certificate) required for authentication request and response processing.

It is also possible for you to specify where the user should land after authentication by including a "target" parameter as part of the query string.

Standalone vs. Embedded Discovery

The discovery service can be either a standalone service or "embedded" within the SP. If your SP will only be interacting with a limited number of IdPs, you may wish to use the embedded discovery service, which is relatively easy to set up. Please see the Embedded Discovery Service page on the Shibboleth wiki.

Try it Out

Once you have Shibboleth installed, you'll need to configure it to point to the Harvard test IdP. In order to help you complete your app registration, we have set up a test IdP that returns sample data. This should be enough to verify that Shibboleth is working properly and help you to think about how your application should consume and use the data Shibboleth makes available.

You'll need to change your Apache configuration to try the new SP. You can specify the paths you wish to have protected by the SP anywhere in your Apache configuration. The Shibboleth SP you installed also includes a file that loads the Shibboleth SP Apache module and protects a sample directory. In order to protect other paths, you can update that file or configure an additional file.

To protect a path, use a configuration block as shown below. This particular configuration requires authentication to access any content from "/protected-area".

For more details on how to access attributes from SAML assertion, see this link in the Shibboleth wiki.
 

Advanced Topics

Multiple Applications

A single Shibboleth SP installation is designed to support multiple applications installed on that server, but there are different deployment and configuration strategies to support this. More information is available at Shib 1.3 Add Separate Application. (Note that these instructions are for Shibboleth 1.3, but the example maps fairly closely to the configuration changes required in 2.x — there is no particular wiki page updated for this particular issue on the Shibboleth 2.x wiki, but you can find all the relevant information in the various API pages.

Downloads

• Production IdP Metadata
• Stage IdP Metadata
• Attribute Map XML

Thanks to the University of Southern California for selected source material for this guide.