====== Discovery ======

<callout color="#ff9900" title="Discovery?">
A Discovery Service is the software that lets users choose their home organization. It redirects them to their identity Provider.
</callout>

A Discovery Service is also known as "WAYF" - "Where are you from?". It establishes the connection between a Service Provider and an Identity Provider via a browser-based selection of the home organization.

There are three ways Discovery can be realized:
  * An SP is configured to redirect to a central public Discovery Service, e.g. one that is run by a federation operator.
  * An SP runs an Embedded Discovery Service itself.
  * An SP is configured to redirect to one static Identity Provider (no Discovery Service in the proper sense, a.k.a "WAYFless URL").

===== DFN's central Discovery Services =====

We run public Discovery Services that can be used by SP operators. These Discovery Services fetch information about available IdPs from the current metadata for DFN-AAI, DFN-AAI-Test, and eduGAIN. 

  * For Shibboleth SPs, the integration is documented on the page about [[en:production#discovery_service|Production]].
  * For SimpleSAMLphp SPs, please refer to their [[https://simplesamlphp.org/docs/stable/saml:sp|documentation]], parameter ''discoURL''.
  * To use the Discovery Service in our test federation, please use the URL ''https://wayf.aai.dfn.de/DFN-AAI-Test/wayf''.

===== Embedded Discovery Service =====
An Embedded Discovery Service (EDS) is run locally on the SP. It also relies on federation metadata to get an up-to-date list of the available IdPs.

In many cases, an EDS is more **user-friendly** than redirection to a central Discovery Service:
  * The selection of home organizations can be designed in the look and feel of the Service Provider. Users are not confused by being rediected to a site that looks completely different.
  * Many SPs are not open to all IdPs in the federation because the SP operators only collaborate with a few home organizations. It can thus be misleading if users of other institutions can select their home organisation although they cannot log in to the service. With an Embedded Discovery Service, SP operators can filter the IdP list accordingly. Therefore, we recommend to run an EDS for Service Providers working with a limited amount of IdPs.

Shibboleth SP comes with a Discovery Service: Shibboleth EDS. The configuration is described on the [[de:shibsp#shibboleth_eds_embedded_discovery_service|Shibboleth SP]] page (in German). For background information please consult the [[https://wiki.shibboleth.net/confluence/display/EDS10/Embedded+Discovery+Service|Shibboleth Wiki]].

===== WAYFless URLs =====

With WAYFless URLs, a Service Provider triggers an Authentication Request with a specific Identity Provider. In this case, only users of that one home organization can access the service.

The configuration of WAYFless URLs often is SP-specific. It depends on the implementation of login on the SP if WAYFless URLs can be used and what they look like. Here are some best practice links:

  * [[https://www.ukfederation.org.uk/library/uploads/Documents/WAYFlessGuidance.pdf|Best Practice: WAYFless Access to Resources - Configuring on a Service and Using in a Portal]] (very detailed)
  * [[https://spaces.internet2.edu/display/inclibrary/Best+Practices|Best Practice recommendations of the US federation InCommon]] (Best Practice #2)

Some SP operators have documented the generation of WAYFless URLs for their platform:
  * [[https://www.conf.dfn.de/anleitungen-und-dokumentation/dfnconf-portal/aai-freischaltung|DFNconf and DFN-Webconf]] (in German)
  * [[https://service.elsevier.com/app/answers/detail/a_id/28537/supporthub/elsevieraccess/|Elsevier]]
  * [[https://idp.nature.com/help/sso#wayfless|Springer Nature]]
  * [[https://www.ukfederation.org.uk/content/Documents/AvailableServices|List of Service Providers in the UK federation]], also applicable for DFN-AAI as URL configuration does not depend on the federation

==== Configuration on a Shibboleth SP ====
On a Shibboleth SP a WAYFless URL has the format. ''<RESOURCE-LOCATION>'' is the protected URL.<code bash>https://<FQDN_SP_HOST>/Shibboleth.sso/Login?entityID=<ENTITYID_IDP>&target=<RESOURCE-LOCATION></code>
    
==== Configuration on a SimpleSAMLphp SP ====
With SimpleSAMLphp a WAYFless URL looks like this by default. ''<AUTH_ID>'' is the name resp. the ID of the authentication source (type: ''saml:SP''), in general ''default-sp''.<code bash>https://<FQDN_SP_HOST>/simplesaml/module.php/core/as_login.php?AuthId=<AUTH_ID>&ReturnTo=<RESOURCE-LOCATION>&saml:idp=<ENTITYID_IDP></code>

{{tag>wayf discovery eds}}