Moving from the legacy WAYF discovery protocol to the DS protocol

Documentation on this page assumes your SP 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 want to move to using the DS protocol with our CDS.

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 then your SP already uses the DS protocol and you should not have to make any changes.

Steps to switch from WAYF to DS protocol with no loss of service

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 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 general steps to migrate from the WAYF protocol to the DS protocol are:

  1. Add a DiscoveryResponse URL to the published metadata. 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 1620 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 spectacularly.

Steps for a Shibboleth SP using the SSO element

The Shibboleth SP has supported the DS protocol for many releases.

Once the DiscoveryResponse endpoint has propagated, you can reconfigure your SP as in our documentation at https://www.ukfederation.org.uk/content/Documents/Setup2SP#SSO and the restart the shibd daemon.

Please be aware that

  • 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
  • this will immediately change the operation of your SP, and won't allow a testing endpoint

Configuration for a Shibboleth SP using the Sessions element

You will need to use the Sessions element and not the SSO element to configure these steps. Please contact the UK federation helpdesk to work through the details.

  • 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 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

OpenAthens SP

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

Other SPs

We don't know, please contact the UK federation helpdesk at service@ukfederation.org.uk