Identity Provider Discovery
When a user would like to login with Shibboleth after accessing a resource directly, the user's home IdP must be identified. That process is known as IdP discovery, and it can be done in a lot of different ways.
Most of the methods for performing IdP discovery involve asking the user directly, because the user can always answer the question best. The question can be posed in many different ways. Since discovery introduces a task for the user and thus creates user interface challenges, doing discovery right is an art that is paramount for the success of any Shibboleth deployment.
Where to Begin
Discovery can either be done using a flat, static page that relies on a fixed, known set of possible IdP's, or done using a dynamic discovery service, a separate app that can generate a set of options based on metadata, present those options to the user, and send the user to the selected home.
Flat Page Discovery
Static HTML leveraging the SP's SessionInitiator support is often sufficient for discovery when there is a limited and static set of IdP's to choose from, and is simple and clean to implement.
From a Known Home
If the user is coming from a source that knows the user's home IdP by definition, that source can send the user directly to the resource, either having already authenticated for that SP, or having preselected the IdP for the user. This can be done on campus portals, URL paths specific to users from one customer, or on library pages, for example.
There are two ways to send the user back to a known home IdP.
The best by far is to utilize a known SessionInitiator at the SP protecting the desired resource and supply it the encoded EntityID for that IdP. For example, TestShib has a SessionInitiator located at https://sp.testshib.org/Shibboleth.sso/TestShib. If supplied an appropriately encoded entityID parameter of https://idp.testshib.org/idp/shibboleth, the SP will examine metadata to determine that it recognizes the IdP, and then select the right endpoints at the IdP and SP automatically. It will dispatch the AuthnRequest directly to the IdP, and the user, upon authentication, will arrive at the resource immediately. The complete request will then look like:
https://sp.testshib.org/Shibboleth.sso/TestShib?entityID=https%3A%2F%2Fidp.testshib.org%2Fidp%2Fshibboleth
This can be placed in any link on any page. The user will authenticate if they haven't already, and they will end up at the application. A separate target can also be added to specify the page at which the user should land.
If the SessionInitiator is not known, then it's possible to forge an AuthnRequest on behalf of the SP based only on information that is present in metadata. This was a common approach with the query string-based authentication requests in Shibboleth 1.x, but it's considerably more difficult with the XML-based, encoded requests in SAML 2.0. It's listed here as an option, but strongly recommended against.
At the Application
If the application knows the set of IdP's that might access it and the set is exceedingly small, then a simple approach to discovery on a flat page might work. For example, TestShib's registration application supports login only through OpenIdP and ProtectNetwork. The simplest and successful approach was to imbed logos for each of the providers on the page in the application itself, with the links going to a SessionInitiator for each provider. These links are very similar to the links described above, but they use a special SessionInitiator for each IdP, and they specify a target resource for the user to land at after authentication.
<a href="https://www.testshib.org/Shibboleth.sso/ProtectNetwork?target=https%3A%2F%2Fwww.testshib.org%2Ftestshib-two%2Fauth-pages%2Fauth.jsp"> <img src="images/PN_sign-in.gif" alt="Login with ProtectNetwork" border="0"> </a> <a href="https://www.testshib.org/Shibboleth.sso/OpenIdP.org?target=https%3A%2F%2Fwww.testshib.org%2Ftestshib-two%2Fauth-pages%2Fauth.jsp"> <img src="images/openidp.png" alt="Login with OpenIdP.org" border="0"> </a>
<center>
<table cellpadding="5" border="1"><tr><td width="200" height="250"><table><tr><td width="200" height="125"><h3 style="text-align: center; margin-top: 20px">
<h3 style="text-align: center; margin-top: 20px">
<a href="https://www.testshib.org/Shibboleth.sso/ProtectNetwork?target=https%3A%2F%2Fwww.testshib.org%2Ftestshib-two%2Fauth-pages%2Fauth.jsp">
<img src="http://www.testshib.org/testshib-two/images/PN_sign-in.gif" alt="Login with ProtectNetwork" border="0"></a></h3></td></tr><tr><td height="125">
<h3 style="text-align: center; margin-top: 20px"><a href="https://idp.protectnetwork.org/protectnetwork-idp/registration.html" target="_new">
<img src="http://www.testshib.org/testshib-two/images/PN_register.gif" alt="Register a new ProtectNetwork identity" border="0"></a><br/><br/>
</h3></td></tr></table>
</td><td width="175" height="250"><h3 style="text-align: center; margin-top: 20px">
<a href="https://www.testshib.org/Shibboleth.sso/OpenIdP.org?target=https%3A%2F%2Fwww.testshib.org%2Ftestshib-two%2Fauth-pages%2Fauth.jsp">
<img src="http://www.testshib.org/testshib-two/images/openidp.png" alt="Login with OpenIdP.org" border="0"></td></tr>
</table>
</center>
Discovery Service
A Discovery Service (DS) is a service that presents a standard interface for users to select their IdP from. A DS presents in some form, highly customizable, a set of IdP's from which the user can choose. After the user makes a selection, the DS redirects the user to the SP, which then formulates the AuthnRequest based on the user's selection.
The user is generally sent directly to the DS in a redirect, but more modern DS implementations(e.g. SWITCH'S WAYF or the Discovery Service) also allow an application to directly embed a discovery interface into a page. The interface can be customized by that page. The following is an example from the SWITCH implementation.
<!-- EMBEDDED-WAYF-START -->
<script type="text/javascript"><!--
// To use this JavaScript, please access:
// https://wayf.switch.ch/SWITCHaai/WAYF/embedded-wayf.js/snippet.html
// and copy/paste the resulting HTML snippet to an unprotected web page that
// you want the embedded WAYF to be displayed
//////////////////// ESSENTIAL SETTINGS ////////////////////
// URL of the WAYF to use
// Examples: "https://wayf.switch.ch/SWITCHaai/WAYF", "https://wayf-test.switch.ch/aaitest/WAYF";
// [Mandatory]
var wayf_URL = "https://wayf.switch.ch/SWITCHaai/WAYF";
// EntityID of the Service Provider that protects this Resource
// Examples: "https://econf.switch.ch/shibboleth", "https://dokeos.unige.ch/shibboleth"
// [Mandatory]
var wayf_sp_entityID = "https://my-app.switch.ch/shibboleth";
// Session Initiator URL of the Service Provider
// Examples: "https://econf.switch.ch/Shibboleth.sso/DS", "https://dokeos.unige.ch/Shibboleth.sso/DS"
// [Mandatory, if wayf_use_discovery_service = false]
var wayf_sp_handlerURL = "https://my-app.switch.ch/Shibboleth.sso";
// URL on this resource that the user shall be returned to after authentication
// Examples: "https://econf.switch.ch/aai/home", "https://olat.uzh.ch/my/courses"
// [Mandatory]
var wayf_return_url = "https://my-app.switch.ch/aai/index.php?page=show_welcome";
//////////////////// RECOMMENDED SETTINGS ////////////////////
// Width of the embedded WAYF in pixels or "auto"
// [Optional, default: 200]
var wayf_width = 200;
// Height of the embedded WAYF in pixels or "auto"
// [Optional, default: "auto"]
var wayf_height = "auto";
// Whether to show the checkbox to remember settings for this session
// [Optional, default: true]
var wayf_show_remember_checkbox = true;
// Logo size
// [Optional, default: true]
var wayf_use_small_logo = true;
// Font size
// [Optional, default: 12]
var wayf_font_size = 12;
// Font color
// [Optional, default: #000000]
var wayf_font_color = '#000000';
// Border color
// [Optional, default: #00247D]
var wayf_border_color = '#00247D';
// Background color
// [Optional, default: #F4F7F7]
var wayf_background_color = '#F4F7F7';
// Whether to automatically log in user if he has a session/permanent redirect
// cookie set at central wayf
// [Optional, default: true]
var wayf_auto_login = true;
// Whether to hide the WAYF after the user was logged in
// This requires that the _shib_session_* cookie is set when a user
// could be authenticated, which is the default case when Shibboleth is used.
// For other Service Provider implementations have a look at the setting
// wayf_check_login_state_function that allows you to customize this
// [Optional, default: true]
var wayf_hide_after_login = true;
// Whether or not to show the categories in the drop-down list
// Possible values are: true or false
// [Optional, default: true]
var wayf_show_categories = true;
// Categories of Identity Provider that shall not be shown
// Possible values are: "category","university","uas","hospital","vho","library","others","upcoming", "all"
// [Optional, commented out by default]
var wayf_hide_categories = new Array();
// Example of how to hide categories
// var wayf_hide_categories = new Array("other", "library");
// EntityIDs of Identity Provider whose category is hidden but that shall be shown anyway
// If this array is not empty, wayf_show_categories will be disabled because
// otherwise, unhidden IdPs may be displayed in the wrong category
// [Optional, commented out by default]
var wayf_unhide_idps = new Array();
// Example of how to unhide certain Identity Providers
// var wayf_unhide_idps = new Array("urn:mace:switch.ch:aaitest:dukono.switch.ch");
// EntityIDs of Identity Provider that shall not be shown at all
// Example of how to hide certain Identity Provider
// var wayf_hide_idps = new Array("urn:mace:switch.ch:aaitest:blupblup.switch.ch", "https://lewotolo.switch.ch/idp/shibboleth");
// [Optional, commented out by default]
var wayf_hide_idps = new Array();
//////////////////// ADVANCED SETTINGS ////////////////////
// Whether or not the new SAML2/Shibboleth 2 flow shall be used that
// sends the user from the discovery service back to the the Service Provider
// Set this to true if you are using a Shibboleth Service Provider 2.x
// [Optional, default: true]
var wayf_use_discovery_service = true
// Session Initiator URL of the Service Provider
// Examples: "https://econf.switch.ch/Shibboleth.sso/DS", "https://dokeos.unige.ch/Shibboleth.sso/DS"
// This will implicitely be set to wayf_sp_samlDSURL = wayf_sp_handlerURL + "/DS";
// [Optional, if wayf_use_discovery_service = true
// or if wayf_additional_idps is not empty, default: commented out]
// var wayf_sp_samlDSURL = wayf_sp_handlerURL + "/Login";
// Default IdP to preselect when central WAYF couldn't guess IdP either
// This is usually the case the first time ever a user accesses a resource
// [Optional, default: commented out]
// var wayf_default_idp = "https://aai.switch.ch/idp/shibboleth";
// Set a custom Assertion Consumer URL instead of
// the default wayf_sp_handlerURL + '/SAML/POST'
// Only relevant if wayf_use_discovery_service is false
// Examples: "https://olat.uzh.ch/shib/samlaa",
// This will implicitely be set to wayf_sp_samlACURL = wayf_sp_handlerURL + "/SAML/POST";
// "https://foodle.feide.no/simplesaml/shib13/sp/AssertionConsumerService.php"
// [Optional, commented out by default]
// var wayf_sp_samlACURL = "https://maclh.switch.ch/foo/bar";
// Overwites the text of the checkbox if
// wayf_show_remember_checkbox is set to true
// [Optional, commented out by default]
// var wayf_overwrite_checkbox_label_text = 'Save setting for today';
// Overwrites the text of the submit button
// [Optional, commented out by default]
// var wayf_overwrite_submit_button_text = 'Go';
// Overwrites the intro text above the drop-down list
// [Optional, commented out by default]
// var wayf_overwrite_intro_text = 'Select your Home Organisation to log in';
// Whether to hide the WAYF after the user was logged in
// This requires that the _shib_session_* cookie is set when a user
// could be authenticated
// If you want to hide the embedded WAYF completely, uncomment
// the property and set it to "". This then won't draw anything
// [Optional, default commented out: You are already logged in]
// var wayf_logged_in_messsage = "";
// Provide the name of a JavaScript function that checks whether the user
// already is logged in. The function should return true if the user is logged
// in or false otherwise. If the user is logged in, the Embedded WAYF will
// hide itself or draw a custom message depending on the
// setting wayf_logged_in_messsage
// The function you specify has of course to be implemented by yourself!
// [Optional, commented out by default]
// var wayf_check_login_state_function = function() {
// if (# specify user-is-logged-in condition#)
// return true;
// else
// return false;
// }
// EntityIDs, Names and SSO URLs of Identity Providers from other federations
// that shall be added to the drop-down list
// The IdPs will be displayed in the sequence they are defined
// [Optional, commented out by default]
// var wayf_additional_idps = [ ];
// Example of how to add Identity Provider from other federations
// var wayf_additional_idps = [
//
// {name:"International University X",
// entityID:"urn:mace:switch.ch:SWITCHaai:internation.university.org",
// SAML1SSOurl:"https://int.univ.org/shibboleth-idp/SSO"},
//
// {name:"Some Other University",
// entityID:"https://other.univ.edu/idp/shibboleth",
// SAML1SSOurl:"https://other.univ.edu/shibboleth-idp/SSO"},
// ];
//////////////////// ADDITIONAL CSS CUSTOMIZATIONS ////////////////////
// To further customize the appearance of the Embedded WAYF you could
// define CSS rules for the following CSS IDs that are used within the
// Embedded WAYF:
// #wayf_div - Container for complete Embedded WAYF
// #wayf_logo_div - Container for logo
// #wayf_logo - Image for logo
// #wayf_intro_div - Container of drop-down list intro label
// #wayf_intro_label - Label of intro text
// #IdPList - The form element
// #user_idp - Select element for drop-down list
// #wayf_remember_checkbox_div - Container of checkbox and its label
// #wayf_remember_checkbox - Checkbox for remembering settings for session
// #wayf_remember_checkbox_label - Text of checkbox
// #wayf_submit_button - Submit button
//
// Use these CSS IDs carefully and at own risk because future updates could
// interfere with the rules you created and the IDs may change without notice!
//-->
</script>
<script type="text/javascript" src="https://wayf.switch.ch/SWITCHaai/WAYF/embedded-wayf.js"></script>
<noscript>
<!--
Fallback to Shibboleth DS session initiator for non-JavaScript users
You should set the value of the target GET parameter to an URL-encoded
absolute URL that points to a Shibboleth protected web page where the user
is logged in into your application.
-->
<p>
<strong>Login:</strong> Javascript is not available for your web browser. Therefore, please <a href="/Shibboleth.sso/DS?target=">proceed manually</a>.
</p>
</noscript>
<!-- EMBEDDED-WAYF-END -->
The DS can be operated by the resource, or it can be run as a central, shared service. There are advantages and drawbacks to either approach.
Run with the Resource
If the resource operates its own DS, it can present the smallest list of potential choices to the user. The resource knows the full set of IdP's it will accept, and it knows which federations it has partnerships with. This is particularly valuable for services serving a large number of communities, or a small subset of a large community.
It can also hint based on additional knowledge it might have, such as a table matching the user's IP address to likely home organizations. The resource can also integrate the branding, look, and feel of the discovery service into its own site.
As a drawback, this requires the SP to maintain its own DS, and can lead to an inconsistent experience for users. Please consult the DiscoveryService documentation to understand how to set up and operate a DS.
Run Centrally
In user testing, consistency in discovery experience has been repeatedly rated as the most important feature. Operation of a central DS creates that consistent user experience. Also, because the DS is centralized, selections made there can persist across all applications that use the shared DS. This can dramatically reduce the number of times the user must select a home.
The central DS is usually operated by a federation. This creates problems for applications that serve multiple federations. As the prospects for a global discovery service appear limited for both user interface and practical reasons, this drawback is likely to linger.