The information on this page has been superseded and should be regarded as historical. For most purposes, you should use the current edition of this document instead.

5 Central Discovery Service

In single sign-on transactions where the user approaches the service provider first, discovery is the process by which the appropriate identity provider for the transaction is determined.

Although discovery is best performed by the service provider itself, the UK federation also makes a central discovery service (CDS) implementation available to participants for their use. For historical reasons, this service is often referred to informally as the federation “WAYF”, an acronym for “Where Are You From”.

5.1 Service Implementation

The CDS is implemented using a number of distinct physical computers in multiple geographic locations. At present, five computers are in use across two locations, but these details are subject to change without notice to allow for service scaling and maintenance.

The service is accessed through the DNS name wayf.ukfederation.org.uk, which resolves to both IPv4 and IPv6 addresses (A and AAAA records) for each machine. These DNS records have a low time-to-live value (currently 5 minutes) to allow rapid reconfiguration of the service to be performed.

5.2 Service Interface

5.2.1 Supported Discovery Protocols

The CDS supports two different discovery protocols: a simple “WAYF protocol” based on the Shibboleth authentication request profile described in [ShibProt], and the more modern and functional “DS protocol” as defined in [IdPDisco].

5.2.1.1 WAYF Protocol

The operation of the “WAYF protocol” is defined in section 2.3 of [ShibProt]. In this protocol, a service provider redirects the user agent to a discovery endpoint with query parameters matching those used by the Shibboleth authentication request profile (urn:mace:shibboleth:1.0:profiles:AuthnRequest) as described in section 3.1.1 of [ShibProt].

Once the appropriate identity provider has been identified, the WAYF redirects the user agent to an SSO service endpoint derived from the metadata for the selected identity provider. This has the effect of relaying the original authentication request message to the selected identity provider without the service provider’s further involvement or knowledge of the selection.

Note that in this protocol the authentication request message contains the assertion consumer service location for the authentication response from the identity provider. This means that the response location (and implicitly the binding or bindings associated with that location in <AssertionConsumerService> metadata elements) must be chosen by the service provider before discovery has been performed: that is, before the capabilities of the selected identity provider are known.

To avoid unexpected failures being presented to the user, the shire parameter MUST refer to an assertion consumer service location which is bound to the SAML 1.1 Browser/POST profile (urn:oasis:names:tc:SAML:1.0:profiles:browser-post).

The WAYF protocol’s limitations are sufficient that it is NOT RECOMMENDED for new service provider deployments. Instead, the DS protocol described below SHOULD be used if supported by the service provider software being deployed.

5.2.1.2 DS Protocol

The Identity Provider Discovery Service Protocol and Profile (“DS protocol”) is defined in [IdPDisco]. Use of this protocol is RECOMMENDED for all new service provider deployments.

Whereas in the WAYF protocol the result of the discovery process is a message relayed to the selected identity provider, in the DS protocol the result of the discovery process is a message returned to the service provider indicating the selected identity provider in terms of its entity ID. This means that the service provider can select the appropriate protocol and profile to use with the particular identity provider rather than being forced to take a “lowest common denominator” approach. In particular, the DS protocol is SSO protocol agnostic and therefore allows the use of both SAML 1.1 and SAML 2.0 profiles rather than being limited to SAML 1.1.

A secondary advantage of this protocol is that problems arising from any mismatch between the profiles supported by the identity provider and the service provider are detected at the service provider. This allows more suitable error messages to be generated than is the case when the CDS is responsible for error reporting.

Note that any service provider making use of the CDS with the DS protocol MUST declare appropriate <idpdisc:DiscoveryResponse> elements in its metadata.

5.2.2 Supported Service Endpoints

The following sections describe the service endpoints supported by the CDS. Service providers MUST NOT use any endpoints at the CDS which are not listed below. 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.

5.2.2.1 Production Endpoints

Service providers capable of implementing the DS protocol SHOULD use the following discovery endpoint with the DS protocol:

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

Service providers not capable of implementing the DS protocol MUST use the following discovery endpoint with the WAYF protocol:

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

5.2.2.2 Test Endpoints

The following endpoints are maintained as alternative discovery endpoints:

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

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

In normal operation, they have the same functionality as defined above for the similarly named production endpoints. From time to time, however, they will be used as ways to expose the next generation of CDS implementation for testing purposes.

The test endpoints SHOULD NOT be used by production service providers except when actively testing next-generation discovery systems.

5.2.2.3 Deprecated Endpoints

The following endpoint location was originally implemented to allow service providers to specify that the user should be able to choose from a list containing all identity providers present in the federation metadata, instead of just those intended for production use:

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

This functionality has now been incorporated into the central discovery service’s user interface (in the form of a “Search over All Sites” link at the bottom of the page) so that it is now possible to access any identity provider from any service provider.

The behaviour of this endpoint is therefore now identical to that of the “/WAYF” endpoint described above and its use is NOT RECOMMENDED.

5.3 Future Directions

5.3.1 Deprecated Endpoints

Discovery service endpoints listed above as deprecated may be removed from the service definition at some point in the future.