IdP Discovery for multi-lateral federation

This page discusses IdP Discovery - the process where an SP allows someone to choose their home organization's IdP during a login attempt. It includes links to potential discovery solutions.

From an IdP's point of view

  • The display name of the IdP is paramount. The IdP operator should choose this name to be easily recognisable as the organization name to the users of the IdP.
  • The UK federation supports additional metadata elements which aid IdP discovery, such as Logos. You can see our IdP-specific recommendations here.
  • An organization can have more than one registered IdP. For example, they may want to register a test IdP for evaluation purposes. In this case, we recommend that the non-production IdP is registered as "Hidden from Discovery" and with a display name that unambiguously states why it is hidden from production, for example by appending " - TEST (do not use)" to the display name.

From an SP's point of view

There are many ways for an SP to offer a choice of IdPs to authenticate at. The UK federation technical recommendations for participants document in section 6.2 recommends use of a local discovery service from which the user can select their identity provider. The service provider can configure such a discovery service to restrict the list of available identity providers to those that are known to subscribe to the service. The list might also be modified according to other properties such as geographical location or client IP address.

Local discovery service

A local discovery service can be implemented by deployment of code which generates a list of links, one for each IdP, where following the link generates an authentication request for that IdP. However the simple list of IdPs does not scale well as the number of IdPs increases. Software products such as the Shibboleth Embedded Discovery Service (EDS) provide additional functions to manage and display large numbers of IdPs. For more information on the Shibboleth EDS please see the Shibboleth EDS documentation on the Shibboleth website.

"Hidden" or "invisible" IdPs in the federation now carry the "Hide from Discovery" entity category, which enables the EDS and similar discovery service software to filter such IdPs out of the IdP list.

The particular configuration required for the Shibboleth EDS to filter out the hidden IdPs is in the SP configuration file. Once you have successfully installed the EDS, you can add the following DiscoveryFilter to your MetadataProvider element. 

  <DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true"
    attributeName="http://macedir.org/entity-category"
    attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
    attributeValue="http://refeds.org/category/hide-from-discovery" />

See the Shibboleth SP MetadataProvider documentation for details.

Offloading discovery to a third party

For SPs that allow authenticated access from a wide range of organisations or for new entrants to federated access, then offloading IdP discovery to another service is a viable option. A specialised service that has been designed to scale, offer search facilities, provide access to hidden IdPs etc. can simplify the deployment of the SP considerably.

The standard protocol to delegate IdP discovery to a discovery service is the Identity Provider Discovery Service Protocol and Profile, commonly called the DS protocol. Many SAML software products such as Shibboleth, simpleSAMLphp and OpenAthens Keystone support this protocol as standard.

Please note: The DS protocol requires that an appropriate DiscoveryResponse endpoint is registered for your SP. Without it, the discovery service does not have a trusted URL to redirect the user back to and will throw an error. Please contact the UK federation helpdesk if you require clarity on this issue.

There are some third party discovery services:

You will have to determine whether the third party service provides the functionality, performance and governance for your application.

Whichever third party discovery service you choose, you will need to configure your SP to redirect to it using the DS protocol. For example, to configure a Shibboleth SP to use this page as a Discovery Service, you would edit the shibboleth2.xml file to include: 

 <SSO discoveryProtocol="SAMLDS"
      discoveryURL="https://wayfinder.openathens.net">
   SAML2
 </SSO>

 <SSO discoveryProtocol="SAMLDS"
      discoveryURL="https://service.seamlessaccess.org/ds/">
   SAML2
 </SSO>

Please note: You will need to ascertain the correct value for the discoveryURL for the service you intend to use. For the meaning of the configurations options please see the Shibboleth SP documentation about the <SSO> element.

This configuration will generate the appropriate DiscoveryResponse endpoint in the SP's automatically-generated metadata. For example, if the SP software is deployed on www.example.ac.uk, you'll find the following endpoint: 

  <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://www.example.ac.uk/Shibboleth.sso/Login" index="1"/>

Some software products do not generate the DiscoveryResponse endpoint automatically so you may have to include a similar endpoint manually.

There are metadata elements that the SP operator can register (such as logos and description) that can aid IdP discovery in any third party discovery service. Find our SP-specific documentation here.

Other sources of information