Moving to the DS protocol from the legacy WAYF discovery protocol

If your Service Provider currently allows people to choose their Home Organization's IdP by redirecting them to the UK federation CDS (Central Discovery Service) using the WAYF protocol, you must reconfigure your SP to use the DS protocol with our CDS.

Why should I re-configure my SP to use the DS protocol?

The DS protocol supersedes the WAYF protocol in several ways:

  • It is protocol-independent and supports SAML 2 and SAML 1 operation, not just the legacy SAML 1 protocol
  • It is less fragile, relying only on the entityID of the IdP rather than the entityID and location of an AssertionConsumerService URL
  • It includes an anti-phishing measure to ensure people are only redirected to trusted URLs

The UK federation therefore deprecated the use of the WAYF protocol on our CDS in June 2017 and will remove support for the legacy protocol in the future.

How can I tell if my SP uses the WAYF protocol?

If your SP redirects people to the CDS with parameters providerId and shire then it is using the WAYF protocol. You MUST take action because the WAYF protocol is deprecated.

If your SP redirects to the CDS with parameter entityID (and not providerId and shire) then your SP already uses the DS protocol and you should not have to make any changes.

How to re-configure your SP

General procedure to switch from WAYF to DS protocol with no loss of service

The general steps to migrate from the WAYF protocol to the DS protocol are:

  1. Before reconfiguring your SP, you MUST ensure that there is a DiscoveryResponse URL registered for your SP. This is the trusted URL that the CDS will redirect people to.
  2. Wait for the new URL to propagate to the CDS. We refresh metadata every day at approximately 1630 UK time and the CDS refreshes metadata every 4 hours, so typically you would wait until the next morning to move onto the next step.
  3. Reconfigure your SP to use the DS protocol instead of the WAYF protocol

You MUST add the DiscoveryResponse endpoint to your SP's published metadata and let that new endpoint propagate to the federations' discovery services before you make any change to the configuration of your SP. If you do not, the remote discovery service will not trust your DiscoveryResponse endpoint and the discovery flow will fail. Note also that the error message that the disocvery service displays is typically incomprehensible to the typical service user.

How to migrate a Shibboleth SP that is configured using the SSO element

The Shibboleth SP has a SSO configuration element that allows simple reconfiguration between WAYF and DS protocols. If your SP is configured using this element, you can reconfigure your SP as in our documentation at https://www.ukfederation.org.uk/content/Documents/Setup2SP#SSO and then restart the shibd daemon.

Please be aware that

  • You MUST register the DiscoveryResponse endpoint before you reconfigure your SP
  • This change will immediately migrate the operation of your SP from WAYF to DS protocol use, and won't allow you to run a separate testing endpoint in parallel.
  • your SP may be configured through the Sessions element rather than the SSO element, especially if you have a complex deployment or if your SP was initially deployed in 2011 or earlier

Configuration for a Shibboleth SP using the Sessions element

If you want to configure a parallel login endpoint to test the DS protocol, or if your SP is configured to use the Sessions element already, please contact the UK federation helpdesk to work through the details. The general shape of the migration is:

  • Register a new RequestInitiator and DiscoveryResponse endpoint suitable for use in the UK federation
  • Reconfigure your SP to support the DS protocol on the new endpoint (enabling SAML 2 operation)
  • Test using the UK federation's Test IdP
  • Test with your customers' IdPs to ensure that any personalisations are retained when moving from SAML 1 to SAML 2 (that is to say, the targetedID has the same value when transported using either protocol)
  • If anyone has an issue, ask them to use the old login link. Tell the UK federation helpdesk and we can negotiate with the IdP operator.
  • Move the login link to use the new RequestInitiator

If you use OpenAthens SP software

The latest version of the OpenAthens SP can now support the DS protocol. As in the above process, you MUST add the DiscoveryResponse endpoint to your SP's published metadata and let that new endpoint propagate to the federations' discovery services before you make any change to the configuration of your SP. If you do not, the remote discovery service will not trust your DiscoveryResponse endpoint and the discovery flow will fail spectacularly.

Typically the endpoint to add to metadata will be of the form 

<idpdisc:DiscoveryResponse
    xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"
    Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"
    Location="https://yourdomain.com/oa/disco-ret" index="1"/>

Some documentation about OpenAthens' use of the DS protocol is at https://docs.openathens.net/display/public/OAAccess/Enabling+OpenAthens+Wayfinder

If you use other SP software

We don't know, please contact the UK federation helpdesk at contact the UK federation helpdesk