Within SURFconext, the discovery page (or: Where Are You From (WAYF) page) is handled by SURFconext. Your Service Provider software only knows 1 Identity Provider, namely SURFconext. The discovery page allows users to select the Identity Provider they want to use to login to your Service Provider. If you offer your service to other Identity Providers outside or SURFconext, e.g. through eduGAIN, you MUST have your own discovery page. 

This page describes what steps you need to take to implement your own discovery page.

The following paragraphs illustrate how to implement a discovery page within eduGAIN:

Background: discovery within SURFconext

For Service Providers connected to SURFconext, a default discovery page automatically appears when users want to login to your service. This will remain so as long as you use the default metadata URL offered by SURFconext:

With this metadata configured, your Service Provider only has 1 Identity Provider, namely SURFconext. SURFconext then automatically redirects the user to a built in discovery page.

For more technical information regarding the discovery page (WAYF) please look at the following page: IdP Discovery - WAYF.

Discovery within eduGAIN

If you want to offer your service to Identity Providers from eduGAIN, you can no longer use the SURFconext discovery page but instead must have your own discovery page. When implementing a discovery page, there are 2 steps to consider:

  1. Build yourself or use available solutions? You can either build your own discovery service or use existing options:
    1. For instance, some SAML implementations already have a discovery feature built in (see below for some examples)
    2. Use a hosted discovery service. This can be as simple as configuring a URL in your SAML software. An option that is known to work and free of chage is:
      1. The Identity Selector Software (thiss.io) also known as seamlessaccess.org.
  2. Metadata: the metadata (see previous step) contains the necessary information of all eduGAIN Identity Providers and Service Providers (such as the name of the Identity Provider, a logo (optional), the technical endpoints, etc.). If your service is only accessible to certain Identity Providers, you might want to apply some filtering (by allow- or blocklisting).
  3. The discovery page itself: using the (processed) metadata, you can now implement a webpage that shows all Identity Providers to the user which are available for logging in. You are completely free to design and implement a discovery page the way you like it. However, there are some do's and don'ts that are mainly about usability listed on the REFEDS website. Please read those before you start working on the discovery page.

Howto's

Some well known software you can use as a Service Provider already have a built-in discovery page:

Howto: SimpleSAMLphp

1. Make sure your SimpleSAMLphp installation uses the correct metadata, the one that includes all eduGAIN Identity Providers. (See here for more info.)

2. Remove any pre-selected Identity Providers from the SimpleSAMLphp configuration.

The default installation of simpleSAMLphp following the instructions on this wiki will set a pre-selected IdP (SURFconext) as the IdP to be used. Since your SP will be connected to multiple IdPs, this pre-selection must be removed.

Change the following line in in the config/authsources.php:

'idp' => 'https://engine.surfconext.nl/authentication/idp/metadata',

to

'idp' => NULL,

By not specifying a particular Identity Provider SimpleSAMLphp will automatically show a built-in discovery page.

3. The default discovery service is likely too basic for your needs. Consider using a different module, e.g. the discopower module.

4. Edit the look-and-feel of the discovery page to suit your needs. Generally it is recommended to use the same styling as the rest of your service, to make sure users do net get confused too much. To read more about changing the look-and-feel of the SimpleSAMLphp discovery page, please look at: https://simplesamlphp.org/docs/stable/simplesamlphp-theming.


Howto: Shibboleth

1. Make sure you use the correct metadata feed, the one that includes the eduGAIN Identity Providers (see previous step).

2. If an EntityID-attribute is specified in the <SSO>-element of the shibboleth2.xml file, remove this attribute from the <SSO>-element.

3. Look at the IdPDiscovery-page on the Shibboleth Wiki for further information regarding the discovery page.

Other options

If the Service Provider software you use does not provide a built-in discovery page, please refer to one of the following other options:

It should not normally be necessary to implement something from scratch.

Final step: set required attributes

For the final step, please look at this page: Set required attributes / ACL.