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

For redundancy, the CDS is implemented using systems in multiple geographic locations. 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, and supports both IPv4 and IPv6 clients.

5.2 Service Interface

5.2.1 Supported Discovery Protocols

The CDS supports two different discovery protocols: the more modern and functional “DS protocol” as defined in [IdPDisco], and the legacy “WAYF protocol” based on the Shibboleth authentication request profile described in [ShibProt]. The WAYF protocol has been deprecated and may be removed with three months notice.

5.2.1.1 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.

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.1.2 WAYF Protocol

The operation of the “WAYF protocol” is defined in section 2.3 of [ShibProt]. The WAYF protocol’s limitations are sufficient that it is NOT RECOMMENDED for new service provider deployments. Instead, the DS protocol described above SHOULD be used if supported by the service provider software being deployed.

In the WAYF 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).

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

5.2.2.2 Test Endpoints

The following were previously maintained as alternative discovery endpoints:

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

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

These endpoints were decommissioned in Summer 2016 as part of a move to new infrastructure and are no longer part of the service interface.

5.2.2.3 Deprecated Endpoints

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

This endpoint has been deprecated and is subject to removal with three months notice.

Although no date has yet been set for the removal of this endpoint, service provider deployers are advised to migrate to the DS protocol endpoint as described in section 5.2.2.1 above.