This page describes how to make use of the DSX Discovery Service for your Service Provider (SP).
Discovery Service Configuration
The eduTEAMS There are multiple options how an SP can make use of the Discovery Service. The simplest one is to just redirect users to the Discovery Service URL serves to discovery requests of the SPs.
| Code Block | ||
|---|---|---|
| ||
https://discovery.eduteams.org/wayf.php |
The protocol is described in Identity Provider Discovery Service Protocol and Profile. On how to apply the Discovery Service URL in your product you should consult the documentation of the product itself, in most cases Shibboleth SP documentation or SimpleSAMLphp documentation.
Embedded discovery.
Discovery may be used also in embedded fashion. For that to work authentication needs to be triggered from a page that includes javascript that provides the functionality. Here we provide examples for Shibboleth SP and SimpleSAMLphp.
Shibboleth SP
This example relies on having eduTEAMS discovery set as default login handler discovery service.
| Code Block | ||
|---|---|---|
| ||
<SSO
discoveryProtocol="SAMLDS"
discoveryURL="https://discovery.eduteams.org/wayf.php">
SAML2 SAML1
</SSO> |
If you use the discovery in embedded fashion you need to include javascript in head element on the page triggering the authentication,
| Code Block | ||
|---|---|---|
| ||
<head>
<!-- HTML elements -->
<script type="text/javascript" src="https://discovery.eduteams.org/ds.js"></script>
<!-- HTML elements -->
</head> |
and then display the element itself that triggers the authentication as defined in default handler.
| Code Block | ||
|---|---|---|
| ||
<a href="/Shibboleth.sso/Login" onclick="startOverlay(event)">Log in</a> |
As a result the discovery is shown in embedded fashion.
SimpleSAMLphp
This example relies on having eduTEAMS discovery set as default sp discovery service.
| Code Block | ||
|---|---|---|
| ||
'default-sp' => array(
'saml:SP',
'entityID' => 'https://sp.example.com/simplesaml/',
'idp' => NULL,
'discoURL' => 'https://ds.eduid.cz/wayf.php',
'privatekey' => 'example.key'
), |
If you use the discovery in embedded fashion you need to include javascript in head element on the page triggering the authentication,
| Code Block | ||
|---|---|---|
| ||
<head>
<!-- HTML elements -->
<script type="text/javascript" src="https://discovery.eduteams.org/ds.js"></script>
<!-- HTML elements -->
</head> |
and then display a element triggering the authentication.
| Code Block | ||
|---|---|---|
| ||
<a href="/simplesaml/module.php/core/authenticate.php" onclick="startOverlay(event)">Log in</a> |
, which we call "central discovery".
| Panel | ||
|---|---|---|
| ||
The DSX Discovery Service (formerly known as eduTEAMS Discovery Service) allows services to implement an (embedded) Identity Provider discovery. After being in a pilot phase, the service was stopped on December 31st 2021 after its decomission was announced already in March 2020. The actual service documentation was/is available on DSX Discovery Service (Pilot). |
Use Central Discovery
For this very basic adoption using the DSX Discovery Service as central discovery service, everything an SP needs to know is the URL that the discovery service uses to serve SAML2 IdP discovery requests. Consult the documentation of the SAML SP product you are using on how to apply Discovery Service URL. If you are for example using the Shibboleth SP, consult the Shibboleth documentation ("discoveryURL") or in case of SimpleSAMLphp the SimpleSAMLphp documentation ("discoURL"). Generic information on the SAML2 IdP Discovery Service protocol are available in the Identity Provider Discovery Service Protocol and Profile.
As for Shibboleth, one would use the following URL as discoveryURL in the <SSO> element of the Shibboleth SP main configuration file shibboleth2.xml.
| Info | ||||
|---|---|---|---|---|
| ||||
https://dsx.edugain.org/wayf.php |
The disadvantage of using a central discovery service is that users are redirected to another host, which has a different look and feel from both the SP they intend to log in to as well as the IDP they intend to log in from.
Screencast to configure Discovery Service with Sibboleth SP
The above steps are also illustrated by the screencast "DSX Discovery Service in 2 Minutes" (uses the old name 'eduTEAMS Discovery Service' instead of DSX) that shows how to do this in 2 minutes with a Shibboleth SP.
Embedded Discovery
For an improved user experience and usability it is, however, recommended to go beyond the basic adoption and take advantage of the IdP filtering features and the embedded discovery. By combining these two features, a SP is able to offer an embedded discovery listing of IdPs that shows only the relevant IdPs for its user base.
The DSX Discovery Service can be seamlessly integrated into a web page of an SP by copy&pasting some HTML/Javascript code.
More details on how to use this on the Embedded Discovery feature.
Filtering the IdPs shown in the list of IdPs
By default the DSX Discovery Service lists all the eduGAIN IdPs.
An SP may reduce the list by using the Filtering IdPs feature.
...