6 Discovery

The SAML protocols are most often used in a service provider first mode of operation, in which the user visits a site providing protected content before providing that site with an authentication assertion.

In this situation, the service provider must send the user to their identity provider bearing an authentication request message. The problem of correctly determining the identity provider to which the user should be sent is referred to as the discovery problem.

6.1 Avoiding Discovery: Institutional Portals

It is possible to avoid the discovery problem entirely by setting up an institutional portal which makes authentication requests to the organisation’s identity provider on behalf of each selected service provider. Such a portal can greatly improve the user experience for members of an organisation with interest in a common set of resources; for example, the students enrolled in a particular class.

URLs suitable for use in such institutional portals can be easily captured by performing a service provider first access to a resource, following the process through to the identity provider and extracting the resulting URL from the browser’s address bar. It is normally necessary to remove the time parameter from such a URL.

One disadvantage of this technique is that it does not adapt to changes in the service provider’s configuration. It is recommended that identity providers wishing to make use of this technique make arrangements with the service providers concerned to be informed in advance of any changes that would affect them. It is also possible for service providers running Shibboleth to set up Session Initiator locations to give identity providers building this kind of institutional portal a more stable, and significantly simplified, interface.

6.2 Discovery by the Service Provider

The discovery process can be completed by the service provider using a number of different approaches. For example, the Shibboleth software sets a discovery cookie on each successful authentication; this can be used on subsequent visits by the client to suggest the most likely identity provider for that particular user. Other heuristics include comparing the user’s IP address against a table of known IP address ranges for different institutions, and making the same resource available at different URLs for different client institutions.

A service provider may also make use of the federation metadata to display a list from which the user may select their identity provider; many service providers will be able to restrict this list to the identity providers for those institutions that are known to be clients of the service. This approach is sometimes referred to as a “local discovery service”.

Performing the discovery process at the service provider is likely to provide a better user experience than the alternative of delegating the process to another entity with less knowledge of the specific service. Service providers are therefore recommended to consider implementing at least partial discovery whenever possible.

6.3 Federation Central Discovery Service

When discovery cannot be avoided through techniques such as institutional portals, and cannot be performed for whatever reason by an individual service provider, recourse may be made to a centralised discovery service provided by the federation. Such a discovery service is often referred to as a WAYF, because the question that it asks is simply: “Where Are You From?”

The federation provides a reliable discovery service hosted on multiple servers at geographically distributed co-location sites. Full details of the service can be found in [UKFTS].

Service providers can make use of the central discovery service through two separate protocols: the newer Identity Provider Discovery Service Protocol and Profile (the “DS protocol”) described in [IdPDisco], and the older “WAYF protocol” described in [ShibProt].

Use of the DS protocol is recommended if the service provider is capable of implementing it. In this case, the service provider should be configured to use the DS protocol with the following discovery location:

https://wayf.ukfederation.org.uk/DS

The legacy WAYF protocol is only recommended for service providers which can not implement the DS protocol. It is much less flexible, and in particular restricts the entities to use of the SAML 1.1 protocol, even when both of them are capable of using SAML 2.0.

To configure a service provider to use the legacy WAYF protocol, use the following URL:

https://wayf.ukfederation.org.uk/WAYF

Any authentication request sent to this location must:

6.3.1 Deprecated Endpoints

All previously deprecated endpoints have been retired.

6.3.2 Use of Undocumented Endpoints

Service providers MUST NOT use any endpoints at the central discovery service which are not listed above or in the corresponding section of [UKFTS]. In particular, endpoints derived from the transient locations shown in a browser’s address bar MUST NOT be used with the CDS, as they are not guaranteed to remain operational.