Deploying, Configuring, Customizing and Managing the IdP Discovery Service

If you just want to install a Discovery Service, go here.

Why Deploy a Discovery Service?

The discovery service is a solution to the IdPDiscovery problem. Briefly summarized, it seeks to solve the problem that an SP has when a user first approaches it:

"Where can I direct this user to go to acquire the credentials I need to allow them access to the pages they are want to visit"

If the SP knows that only one IdP will ever provide authentication then it can immediately send the user to that IdP. However an SP will usually be able to handle users authenticated by multiple IdPs and at that point it has no option but to ask the user to select an IdP, this work is usually done by a IdPDiscovery service.

Although this solution is deceptively simple it is complicated by several factors:

Any user interaction associated with this operation will be the first that the user ever sees and hence will define the user's opinion of the SP.
Even returning users may not be aware of precisely what is being asked of them ("What is a Federation?", "What is an IdP?", "Why do I need to do this?")
An independent service is not well positioned to provide simple choices because it has to make broad assumptions as to which IdPs might be of interest. This has two potential side effects:
- It will offer a confusing list of IdPs to the user
- It can allow a user to select an IdP which cannot provide authentication to the SP.
SPs are very often members of more than one Federation

These issues can be minimized by associating a discovery service with each SP. Thus deployed the discovery service can:

Have a similar look and feel to the rest of the SP.
Provide assistance in selecting the IdP in a way which is targeted at its particular users base.
Limit those IdPs which the user is asked to chose from to those which the SP is willing to accept authentication from (for commercial, technical or other reasons).

In addition to per-SP discovery services, most federations deploy a discovery service. This serves as the 'back stop' service. It is considered best practice that SPs have a specific discovery service, however those SPs which are only in one Federation can rely on this Federation-deployed discovery service.

Example

As an example, consider a commercial SP with contracts with three institutions: Institution A is a member of InCommon, Institution B is a member of the UK federation and Institution C is a member of the Switch Federation

When a user approaches the SP, they should not be presented with a list of all the IdPs known to all three Federations, as the SP only needs to know which of these three IdPs the user needs to be sent to. The SP can provide guidance to the user in selecting one of these couched in terms that their target audience can understand.

What does the Discovery Service do?

In Shibboleth version 1.3, the discovery service takes an AuthnRequest message as input and, as a result of interaction with the user, forwards this message on to the selected IdP.

The discovery service can keep track of the IdP that was selected by using the browser cookie specified in the Identity Provider Discovery Profile. However this can only store the fact that an IdP was selected, not whether the user authenticated successfully (in which case the user might wish to change their choice of IdP). Hence, by default the discovery service does not automatically redirect the request to the last selected IdP, instead a list of the most recently selected IdPs is provided as a hint.

The discovery service uses SAML2 metadata to find out about the Entities (SPs and IdPs) that it interacts with. For a per-federation discovery service this is usually the same as metadata which the federation publishes. For an SP-specific discovery service this input metadata would be constrained to only list the relevant SP and IdPs. Once deployed, the discovery service watches the metadata files and will reload them as soon as they are changed.

Deploying the Discovery Service.

The discovery service is highly configurable and the person deploying it can control:

The look and feel of the user interface.
How Many metadata files the discovery service can consult.
The precise semantics of the interaction with the end user.

The discovery service is deployed in Tomcat. The following sections assume that you have Tomcat running and understand how to deploy packages into Tomcat.

You must endorse a set of Java libraries used by Shibboleth that parse XML to override obsolete classes that Sun includes with their JVM. Tomcat 5.0.x additionally requires that endorsed Xerces libraries packaged with it, xercesImpl.jar, xml-apis.jar, and xmlParserAPIs.jar, be deleted first. These libraries are shipped in the endorsed subdirectory of the kits.

Downloading the Discovery Service

The discovery service is available as a binary distribution in zip and tgz format from the shibboleth download site. The current version is 1.0-RC1. Alternatively, the sources are available in SVN.

Configuration: Simple Deployment

Unpack the distribution into a staging area and edit the install.properties file. This allows you to define where the metadata and configuration files will be stored. Then run either ant.sh (on Unix systems) or ant.bat (on Windows systems) as a user which has the ability to create the DS home directory you specified in the install.properties file. If you wish to change the look and feel, edit ?webpages/wayf.jsp? (in the staging area) prior to running ant.

The default configuration files are for a very simple configuration. This has an Internet2-branded look and feel and works from a single metadata file which is located at DsHomeDirectory/metadata/sites.xml (where DsHomeDirectory was specified in install.properties).

To change the location for the metadata file: edit the file called "DsHomeDirectory/wayfconfig.xml" and change the line

uri="file://XXXX/metadata/sites.xml"

as appropriate. Note the URL does not have to be a file, it can be an HTTP URL.

Finally copy the war file in the Ds Home Directory into the appropriate place for your container.

If you wish to change the configuration you can edit wayfconfig.xml at any time. These changes will be collected the next time the discovery service starts. Changes to the jsp file require that ant be run again. Metadata changes (including remote ones) will be collected as they happen.

Advanced Deployment

A single discovery service can have multiple different personae. Each persona (known as a Discovery Service Handler) can have its own GUI and metadata sets. The address at which each handler is available is configured in the WEB-INF/web.xml file. This is the only configuration available in this file.

By default the discovery service listens on all URLs which end in ".wayf". Precisely which handler is involved and how each handler behaves, is controlled by the contents of the configuration file (src/conf/wayconfig.xml). This determines:

How many discovery service handlers there are.
Which URLs each handler listens on
The user interface (defined by a separated jsp file) for each handler
Which metadata file(s) the handler uses.
Other detailed semantics
The default configuration and jsp files contain copious comments to help deploying complex discovery services.

Again, once configuration is complete go to the top level directory and type 'ant'. This will build the Discovery Service distribution into the 'dist' directory.

Management

Once deployed, the only routine management required is to ensure that metadata specified as coming from files be refreshed frequently. The discovery service reloads metadata as soon as it notices that it has been changed, and hence it is not necessary to restart it the after updating the metadata.

Metadata which is loaded from a URL need not be refreshed since the Discover Service will do that for you.

Metadata does not have to be signed

Logging

The Discovery Service uses the Logback logging system. The Logback manual provides an exhaustive set of directions and available options that may be configured.

The logging configuration is located at $DS_HOME/logging.xml.

Alternative

You could also deploy the PHP based WAYF from SWITCH, it offers multi-language support and several usability enhancements.

Browser not supported