This page is intended to provide best practices for InCommon participants.  These best practices are all geared towards library resource providers and libraries.

Resource Providers

Resource providers deal with a variety of authentication challenges and often have to support several authentication schemes simultaneously.  Shibboleth is just one of those schemes.  These best practices should serve as a guideline for resource providers that are implementing Shibboleth.  These best practices have been written by InCommon member institutions that have experience integrating Shibboleth as an authentication option for library resources.

If all of these best practices are followed, libraries will be able to maintain the seamless access they can currently provide with IP-based authentication, and also have the groundwork laid for future developments such as personalized services.  As there are many resource providers and all have different platforms and services, there is no expectation that all will be able to implement these best practices immediately.  So, these best practices are laid out as building blocks or steps in the implementation path.  These steps are listed below and then each is further defined below.

1. Implement WAYFless URLs.
2. Implement authenticated direct links to resources.
3. Shibboleth/EZproxy hybrid compliance
4. Authorization via eduPerson attributes

Step 1: Implement WAYFless URLs

Simon McLeish coined the term WAYFless URL, and there is plenty of discussion of the term and its meaning on his wiki.  In brief, WAYFless URLs are urls to resources that allow for bypassing the Shibboleth Where Are You From (WAYF) step.  For our purposes, this means providing a URL syntax such that a resource URL could be cleverly crafted to navigate the user through the authentication/SSO process without prompting the user to identify their institution.

There are two acceptable forms of WAYFless URLs.  The first is Session Initiators implemented by the resource provider.  The second is a SSO location provided by the identity provider.  Each of these is described below, along with some indication of what is required to implement each by the resource provider.

Session Initiators

Session Initiators are URLs that exist on the resource provider site, that can accept two parameters, a resource location and an identity provider's entityID, and properly direct the user through the appropriate identity provider for authn and then on to the resource location, without requiring the user to identify where they are from.  The syntax of a session initiator URL is as follows:

http://resource-provider-site/session-initiator-url?entityID=IDENTITY-PROVIDER-ENTITYID&target=RESOURCE-URL

With session initiators, the library creating WAYFless URLs would need only know the location of the session initiator URL, their own campus' identity provider entityID, and the URL of the resource they are trying to link to.  JSTOR is an example of a resource provider that has implemented Session Initiators:

http://www.jstor.org/start-session?entityID=provider-uri&target=target-url

The Shibboleth service provider software implements Session Initiator URLs natively.  Information about their configuration is available on the Shibboleth 2 wiki, https://spaces.at.internet2.edu/display/SHIB2/NativeSPSessionInitiator, and there is some more basic discussion on the Shibboleth 1.x wiki: https://spaces.at.internet2.edu/display/SHIB/SPMainConfig.  For a resource provider, this is only part of the implementation, obviously this must integrate and play well with other supported forms of authentication.

Identity Provider SSO

A very good description of this type of WAYFless URL is given by Simon McLeish on his wiki page, WAYFless URL, under the secion, General Form.  So, we won't recapitulate all of the detail here, but will copy the basic elements of this type of WAYFless URL here.  The general form of a WAYFless URL for a Shibboleth protected resources is:

SSO_LOCATION?target=RESOURCE_LOCATION&shire=AC_SERVICE_LOCATION&providerId=PROV_ID

where:

• SSO_LOCATION is the URL of the single sign on service of the Identity Provider to use for authentication (which can be found in the IdP configuration files or federation metadata)
• RESOURCE_LOCATION is the URL which is to be accessed following the establishment of a Shibboleth session
• AC_SERVICE_LOCATION is the URL of the Assertion Consumer Service of the Service Provider (which can be found in the federation metadata)
• PROV_ID is the identifier of the Service Provider within the federation used for access (which can be found in the federation metadata)

In order for resource providers to support this type of WAYFless URL, the resource provider site must be able to establish their own sessions after someone has been authenticated via Shibboleth.

Libraries