Shibboleth Service Provider Installation at USC

Contents

Introduction

This guide describes the process of installing and configuring a Shibboleth Service Provider to work within the USC environment.

Both Shibboleth 2.x and 3.x setup information are provided. Most information applies to both environments, however where there is a difference, the applicable installation will be appropriately tagged. Setup of 2.x service providers is now deprecated and, although it works and may be needed in some extreme circumstance, should not be used.

Intended Audience

This document is intended for the system administrator that will be installing and maintaining a Shibboleth service provider at USC. This may be a different person than the application developer who will actually be using the attributes which Shibboleth delivers. The following basic skills are expected of the reader, and are beyond the scope of what this document attempts to cover:

Policy

It should be noted that this document covers only the technical aspects of setting up Shibboleth and does not attempt to include the equally important policy requirements of accessing the USC Global Directory Service (GDS). In order to have the USC Identity Provider release attributes to your application, a request must be made to and approved by the USC Directory Steering Committee. Until this request is made and approved, no production data will be released to your application. More information on this process can be found on the GDS website at http://www.usc.edu/gds/.

Install Shibboleth

The Shibboleth project offers documentation for installing Shibboleth on various platforms. Follow the appropriate Service Provider Installation instructions at:

Configure Shibboleth for Test IdP

Once you have Shibboleth installed, you'll need to configure it to point to the USC Shibboleth Test Identity Provider. Until you have completed the attribute request to the Directory Steering Committee real data cannot be released to your application, so we have setup a test IdP that will return sample data. This should be enough to verify that Shibboleth is working properly and begin thinking about how your application should consume and use the data Shibboleth makes available.

The location of the following configuration files will vary depending on which Shibboleth installation package you used. The most common locations are

Shibboleth XML

This is the primary configuration file for Shibboleth 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 Identity Provider. Fill out the following form to have your configuration file automatically generated for you.

Entity ID:

An Entity ID is a URI that uniquely identifies your application to the central Identity Provider. We generally recommend using a URL of the form https://www.usc.edu/department-name/application-name/shibboleth-sp, where http://www.usc.edu/department-name/ actually does go to your department's webpage. The full provider ID itself does NOT actually need to resolve to anything, it is just used as an identifier for your application. If your application has its own redirect off of www.usc.edu or its own hostname, it is acceptable to use either of those. A few real-world examples:

  • Libraries Proxy Service: https://www.usc.edu/libraries/proxy/shibboleth-sp
  • myUSC Portal: https://www.usc.edu/portal/shibboleth-sp
  • iTunes U: https://itunes.usc.edu/shibboleth-sp
More information on entity ID naming can be found at EntityNaming.

Application URL:

The actual URL which will be used to access your application. This may be the name of the physical machine and a path(such as http://app-server1.usc.edu/myApplication/) or it may be an alias setup for your application (such as http://my.usc.edu).

Support Email:

This address will occasionally be displayed on Shibboleth error pages so that end users know who to contact when something unexpected occurs with your application.

Distribution:
Windows
RPM with Red Hat File Layout
Standard (/opt/shibboleth-sp)
ITS Solaris (/var/local)
Custom Prefix:
Generate configuration text in a new window:

This form will generate a shibboleth2.xml file that should be used to replace the existing one in your shibboleth configuration directory (make sure you keep shibboleth.xml.dist around so you can refer to it later). Go ahead and look through your new shibboleth.xml and get a feel for what all it contains and what files on your local system it references (notably the certificates at the bottom of the file). For the sake of simplicity a number of assumptions are made (such as the use of standard TCP ports); if these are not true for your environment, a full description of everything in this file can be found here:

Metadata

Download the USC metadata file from https://shibboleth.usc.edu/USC-metadata.xml and place it in your main shibboleth configuration directory. Make sure this location corresponds with the uri attribute of the MetadataProvider element in your shibboleth.xml or shibboleth2.xml file.

Credentials

An X.509 (SSL) certificate is required to encrypt data between servers and provide server authentication.

It is highly recommended that you simply use a self-generated certificate and key pair. If you have installed an SP by compiling it yourself or using the Windows installer, a certificate and key pair will be generated for you. If you are using a prepared system install (such as in /usr/usc on Solaris if/when that is available) you will need to generate your own. The best way to generate the cert is to use the script keygen.sh (or keygen.bat on Windows). This script is available in the etc/shibboleth configuration area near where the shibboleth.xml or shibboleth2.xml file is located. This script will automatically generate a certificate for you and store it in the files sp-cert.pem and sp-key.pem.

If you really can't or do not want to use that method and you already have a certificate from VeriSign or Thawte, you may simply use that. Save both your certificate and key on your server and make sure that the CredentialResolver in your shibboleth2.xml accurately reflects the locations of these files.

Important note when updating certificates: An updated certificate must be generated using the same key or it will break communications between the SP and the IdP until the new matching certificate is recorded in the IdP. So, for example, if you have used your front-end webserver cert and listed it as the cert to use with the shibboleth service, updates to the webserver cert can break shibboleth services. To avoid this type of common maintenance pain, keep the shibboleth certificate and key separate, self-signed, and long-lived.

Attribute Access

Testing Shibboleth

Request Map

The RequestMap by default is configured to only protect a directory named "secure". This should be modified to define the actual URLs of your application that should be protected. A lot of information on protecting resources is available here:

Confirming attribute release

A good way to test your installation is to use a test script which will display the environment and headers of your application. This can be used from "/secure" or any protected location you configure using the RequestMap or the equivalent Apache commands. Test scripts which directly show the environment are available here: http://shib.kuleuven.be/download/sp/test_scripts/ in your /secure directory in order to see the HTTP headers being populated.

If you don't want to bother with a script, most browsers have a developer console available through a menu item or installable as a plugin. These browser tools can show you the headers.

Another good way to test is to use the built-in service provider session information service. This service is accessed by constructing a URL based on the hostname plus the contents of your "handlerURL" setting plus "/Session". For example, for the sample service provider installation, this value is: https://shibboleth-test.usc.edu/docs/sp/install/Shibboleth.sso/Session

Inside the shibboleth2.xml is a configuration block described by a comment "Session Diagnostic Service". It looks like this:
<Handler type="Session" Location="/Session" showAttributeValues="false" />
It may not have the showAttributeValues option at all, but if you add it and set it to true, you will be able to see the actual values provided to the session. The default is false, so this is best used for testing and then when not needed anymore, set it back to false.

Attributes Received

If successfully configured, you should receive the following attributes from the Test Identity Provider. This is only sample data, but is formatted to look exactly like the production data will. For example, all entitlement values will begin with urn:mace:usc.edu:gds:entitlement but the last portion will vary between applications. Also note that you will be receiving multiple entitlement values — be aware of how multi-valued attributes appear to your application (semi-colon delimited).

urn:mace:dir:attribute-def:mail tommy.trojan@usc.edu
urn:mace:dir:attribute-def:displayName Tommy Trojan
urn:mace:usc.edu:gds:attribute-def:uscPvid stbm3sj4
urn:mace:dir:attribute-def:eduPersonEntitlement urn:mace:usc.edu:gds:entitlement:stdr9ph2
urn:mace:usc.edu:gds:entitlement:stmn7vt3

After all of this is setup, you should have something similar to https://shibboleth-test.usc.edu/docs/sp/install/sample.

Move into Production

When the Directory Steering Committee has approved your attribute request you will be able to point to the production Identity Provider and receive live data from the GDS. This will require only a few very minor changes.

Change hostnames

The hostname shibboleth-test.usc.edu appears twice in your shibboleth.xml file, as part of the SessionInitiator and SingleLogoutService elements. Replace both of these instances with shibboleth.usc.edu.

Create ticket with metadata or shibboleth2.xml and certificate

You will need to create a ticket containing your exported metadata file or your shibboleth2.xml configuration file and SSL certificate (NOT the SSL key) so that your metadata can be imported and the IdP can be configured to release the appropriate data to your application.

A note about credentials

At this time, the Test Identity Provider does not actually authenticate Service Providers with the SSL certificate they present. This means that while your SP may operate correctly with the test IdP, it may fail with the production IdP due to misconfigured certificates. This may not be obvious at first, so if you have problems when moving your SP to the production IdP, we recommend you email the shib-discuss mailing list.

Attributes

When you move to the Production IdP, the attributes your application receives will likely differ from those you received from the Test IdP. The attributes released to your application will be based on what was included in your request to the Directory Steering Committee (see Policy) and may require changes to your attribute mapping file: attribute-map.xml

Strategies for Limiting Access

All users that are authorized to use your application are granted a specific eduPersonEntitlement value, which should be delivered to your application. In order to verify that a given user is indeed authorized, you'll need to look for this entitlement value, which can be done a number of ways:

It is not appropriate to use any other attribute to determine if a given user is authorized to use an application. Doing so introduces additional assumptions about what attributes a user may have, that may not be true for all users at all times.

A note about timestamps

It is very important to keep your server synchronized with a Network Time Protocol (NTP) service. USC Solaris servers connect to a set of USC-provided NTP servers. The following example entry in the root crontab file can keep your service up to date:


16 3,9,15,21 * * * exec ntpdate ntp1 ntp2 ntp3 >/var/adm/ntpdate.log 2>&1

Alternatively, if you have a Windows server, you can set the server to automatically keep up-to-date using the "Date and Time" tool in the control panel and then accessing the "Internet Time" tab. Make sure the checkbox is checked next to "Automatically synchronize with an Internet time server" In the "Server: " box, you can choose any NTP service you wish, or you can enter, for instance, "ntp1.usc.edu" into the box. Click "Update Now" to verify that it is working.

Failing to set regular NTP updates will usually lead to a sudden loss of Shibboleth services after some long period of time when the drift of the internal hardware clock suddenly exceeds the skew window. For more information see: Shibboleth Clock Skew

Advanced Topics

Understanding Logout

The current version of Shibboleth does not support single logout, so it is important to understand what options are available to your application. The only way for a user to completely log out of all Shibboleth services is to close their browser. Short of that, the present recommendation is to first do whatever clean up is necessary within your application and then redirect the user to the Shibboleth SP SingleLogoutService. This URL is dependent on your installation and is constructed as a combination of your hostname, handlerURL, and SingleLogoutService location (all defined within shibboleth2.xml). It will likely be of the form https://my-app.usc.edu/Shibboleth.sso/Logout. When the user is redirected to this URL, their Shibboleth SP session will be destroyed and they will be redirected to the Shibboleth IdP logout URL. At this point, their Shibboleth IdP session will be destroyed and instructions will be provided for truly completing the logout if they wish (ie. closing their browser).

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 here: Shib 1.3 Add Separate Application Those instructions are for shibboleth 1.3, but the example maps pretty closely to the configuration changes required in 2.x and 3.x -- there is no particular wiki page updated for this particular issue on the Shib 3.x wiki, but you can find all the relevant information in the various API pages.

Lazy Sessions

For some applications, it only makes sense for authenticated users to use the application. For example, what would an unauthenticated user do at a webmail application? Not much, most likely. However, there are many applications where it does make sense to offer a basic set of services to anonymous users and additional services only to authenticated users. In these case, it may be useful to make use of a feature in Shibboleth known as "Lazy Sessions" (sometimes referred to as "passive sessions"). Find out more at LazySession (Again, note that this is information on the Shib 1 wiki which also applies generally to Shib 3.x).

Federated Access to Applications

Shibboleth SP installations support logins from any identity provider configured. Some applications may be more open to access from external institutions. Institutions wishing to share information with each other generally join what is called a "Federation" and these institutions then can set up a trust framework which streamlines the approach to enabling trusted access to applications between institutions.

USC is a member of the InCommon Federation. As such, we have the ability to more easily log in to applications at member institutions, and we can also set up applications which allow logins from members of those institutions. A list of the member institutions can be found here.

Setup for Federated Access

Several configuration changes to the shibboleth2.xml will be required when enabling federated access. Policies regarding institutions which are allowed access may also be needed in the attribute-policy.xml. Additional attribute definitions may also be needed in the attribute-map.xml depending on which attributes are released by the institutions you allow to login.

First, you will need to load the metadata for the participating institutions. To do this, replace the MetadataProvider element with this one:

        <MetadataProvider type="Chaining">

<!-- Use this MetadataProvider to federate with only those IdPs that are supported. -->
           <MetadataProvider type="XML" 
                             url="https://shibboleth.usc.edu/ds/supported-idp-metadata.xml"
                             backingFilePath="/var/local/etc/shibboleth/USC-metadata.xml"
                          reloadInterval="86400"/>

<!--
For applications that wish to federate openly with InCommon participants, delete the above
MetadataProvider and use this one.
           <MetadataProvider type="XML" 
                          url="http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml" 
                          backingFilePath="/var/local/etc/shibboleth/incommon-metadata.xml" 
                          reloadInterval="86400"/>
-->

        </MetadataProvider>

Next, you will want to set up a custom login form which will enable access from the institutions we participate with. This is very flexible and allows you to specify as many or as few of the InCommon participants as you wish, however, in order to use the USC central directory information about these guests, it is recommended to use the login form which dynamically accesses this list from the shibboleth.usc.edu server. This set of example files will provide a foundation for your login page, subject to your styling and customization changes. (Hint -- search for references to "myfederatedapp" and replace it with the name of your application).

To use this login form, it is necessary to customize the SessionInitiator element in the shibboleth2.xml. Normally, for an application located at myserver.usc.edu/myfederatedapp, there will be an ApplicationOverride block at the end of the shibboleth2.xml which provides an area for custom settings for this application.

By default, there is a Sessions element there, and it looks something like this:



          <Sessions handlerURL="/myfederatedapp/Shibboleth.sso" 
                    handlerSSL="true" 
                    cookieProps="; path=/myfederatedapp; secure" 
                    checkAddress="false" 
                    lifetime="7200" timeout="3600" />


This should be changed to the following, replacing the application name and path to the form as appropriate:



          <Sessions handlerURL="/myfederatedapp/Shibboleth.sso" 
                    handlerSSL="true" 
                    cookieProps="; path=/myfederatedapp; secure" 
                    checkAddress="false" 
                    lifetime="7200" timeout="3600" >

            <SessionInitiator type="Chaining" Location="/DS" 
                              id="myfederatedapp-sessioninit" 
                              forceAuthn="false"
                              relayState="cookie"
                              acsByIndex="false"
                              >
              <SessionInitiator type="Cookie" isDefault="true" />
              <SessionInitiator type="SAML2" acsIndex="1" template="bindingTemplate.html"/>
              <SessionInitiator type="Shib1" acsIndex="5"/>
              <SessionInitiator type="Form" relayState="cookie" template="/var/local/full/path/to/fed-form.html"/>
            </SessionInitiator>

        </Sessions>


If these pages and stylesheets are served from somewhere within the protection of shibboleth, it will be necessary to remove the requirement for a shibboleth session on the particular web location that serves these forms, for instance by using an Apache directive such as:



        <LocationMatch /myfederatedapp/(images|styles|SP)/>
                AuthType shibboleth
                ShibRequireSession Off
        </LocationMatch>


To enable the provisioning of entitlements and data from the USC environment, it will be necessary to reconfigure the AttributeResolver. Normally, this is in the shibboleth2.xml and looks like: 



        <AttributeResolver type="Query"/>


This should be changed to the following:



        <AttributeResolver type="Chaining">
          <AttributeResolver type="Query"/>
          <AttributeResolver type="SimpleAggregation" attributeId="eduPersonPrincipalName" format="urn:oid:1.3.6.1.4.1.5923.1.1.1.6">
            <Entity>urn:mace:incommon:usc.edu</Entity>
            <Attribute Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.7" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" FriendlyName="eduPersonEntitlement"/>
          </AttributeResolver>
        </AttributeResolver>


Additional requested Attribute entries may be needed according to your committee-approved attribute release permissions. Though, this rule will retrieve all attributes configured for release by the IdP release policy.

Attributes from federated entities ususally release EPPN, and sometimes just an opaque persistent identifier. Some sites such as ProtectNetwork release additional fields such as name fields for display. This attribute-map.xml contains additional attribute definitions to help with decoding the attributes released by partner organizations.

One final optional configuration which might be needed is to set aside the federated login part on a separate link while the main application continues operating as it usually does from the main links. This is done by configuring the Host/Path blocks at the top of the shibboleth2.xml file and using the requireSessionWith directive. This will configure a particular link to use the SessionInitiator with the id specified in the requireSessionWith directive. The original SessionInitiator must be copied into the ApplicationOverride so that it is used for regular access to the application if needed. For example: 



            <Host name="myserver.usc.edu"
                  applicationId="myfederatedapp"
                  authType="shibboleth"
                  requireSessionWith="sessioninit-orig"
                  exportAssertion="false">
                <AccessControl>
                    <Rule require="entitlement">urn:mace:usc.edu:gds:entitlement:sctxxxxx</Rule>
                </AccessControl>
                <Path name="federatedloginlink"
                      applicationId="myfederatedapp"
                      authType="shibboleth"
                      requireSessionWith="sessioninit-fed"
                      exportAssertion="false"/>
             </Host>

Additional Resources