Embedded Discovery Service 1.0 Details

This document describes the Shibboleth Embedded Discovery Service (EDS).

1 Goals

There are two main goals for version 1.0 of the EDS are:

Improve the user experience during the login process
Provide an easy way to "embed" the EDS into a service providers site.

In addition, the development team wishes to update the core code of the centralized discovery service, which has languished relative to the other Shibboleth project code.

2 Improved User Experience

To say that the current user experience is rough is being generous. Organizations have become increasingly aware of this issue. Therefore, in addition to the code change, the EDS 1.0 work has developed a set of recommended visual elements as well. The result of these recommendations is a user experience with consistent visual elements across service and identity providers regardless of organization and federation boundaries.

Web site designers, please note, none of these recommendations require any changes to your site's overall look and feel. Everything recommended herein is explicitly meant to be embeddable within your existing site. These recommendations only attempt to standardize the various visual elements exclusively related to the federated log in process.

2.1 Initiating the Process

The first recommendation addresses the placement of the initial "authentication kick off" button/link. The current recommendation is to place a "Login" link or button in the upper-right corner of the service provider's web page. The button/link should say "Login" as this is a term understood by nearly all users, as opposed to things like "Shibboleth", "Federation(ed)", "Athens", and other, more technical, terms often used in this area.

Figure 1: SP front page with "Login" link in upper-right corner

In the interest of full disclosure, this recommendation seems to be the most contentious with some people. However, one of the underlying themes running through all of this UI work is to create suggestions that are a) better than what is currently out there and b) acceptable to the majority of deployers.

2.2 IdP Selection Page

The majority of the redesign work in the whole log in flow occurs on this page.

First, for many years now, the recommendation of the Shibboleth team has been that service providers should really embed the IdP selection page into their website. This way users aren't hit with a jarring change resulting from the introduction of a discrete discovery service website. However, the Shibboleth project never really provided any tools to make SP-side IdP selection pages easier. That will change (see below).

So, the recommendation continues to be to embed the IdP selection page within the service provider's web site and for the IdP selector to take on certain UI elements (e.g. color, fonts) of the site. The EDS, however, will have consistent UI elements between all sites in order to allow users to feel comfortable when they see it, even if they've never been to that particular SP before.

Figure 2: Initial IdP selection page embedded in SP webpage

2.2.1 Preferred IdP Pane

The top portion of the EDS, known as the preferred IdP pane, displays a set of "preferred" IdPs. An IdP is preferred if either the EDS deployer has specifically stated it as preferred in their configuration, or if the user has previously selected the IdP. The EDS will always display the SP configured preferred IdPs first, but it will always reserve at least one spot for a user selected IdP. So, for example, if the preferred IdP pane has three IdPs in it, and the SP has configured 4 preferred IdPs, only the first two will be shown and the third slot will be a user selected IdP. The preferred IdPs are represented by both an image button, bearing the logo of the IdP, as well as a textual link bearing the IdP's name.

Figure 3: IdP selection page showing previously selected IdP to the right of SP configured preferred IdP

2.2.2 IdP Selection Pane

Below the preferred IdP pane is the IdP selection pane. By default, this is a text input box with a label asking the user to enter the name of their organization. As users type, a drop down list of selections appears.

Figure 4: IdP selection page showing "search-as-you-type" feature

Alternatively, the user may click on a link that will replace the text input field with a drop-down selection list. This is useful if the user is unsure what name to enter (e.g. if they are a member of multiple organizations and are not sure which, if any, are federations members).

Figure 5: IdP selection page showing drop-down selection list feature

Finally, there is a "Continue" button, specifically labeled Continue to indicate that there are additional steps to perform.

2.2.3 Further Information Pane

Below the IdP selection pane, is a link that leads off to a document explaining exactly what is occurring and what the user should expect as they move through this log in process.

2.2.4 Obscured Features

There are three things that are not readily apparent from just looking at the screenshots. First, everything displayed may be localized. The labels, the "what is this" link, and the "Continue" button text are configured by the SP while the localized logos and names come from the metadata for the IdP.

The second thing not immediately obvious is the use of "hinting" in the IdP selection pane. Hinting is the act of taking data know about the user at the time (e.g. things like their IP address) and using it to propose, or favor, certain selection options by moving them up to the top of the selection list.

Finally, all the data displayed in the embedded discovery box is designed to be accessible to individuals with various types of sight or movement impairments. For example, everything in the box is keyboard-navigable, the display can be easily rendered in high-contrast colors, and everything displayed can be easily read by screen readers.

2.3 IdP Authentication/Consent Page

The next step in the log in process is the authentication page displayed by the IdP to the user. With the EDS embedded in the service provider's website, this is now the first time the user leaves the SP website. In order to decrease user confusion, the authentication page will now carry the logo, name, and description of the SP. This should help users understand that they are still involved in a process related to authenticating to that service.

Figure 5: IdP authentication page showing SP logo and details.

If the IdP also has an attribute release user consent engine (like uApprove) installed, the same SP data will show up on that page as well, for the same reason.

2.4 What Isn't Here

Just as important as the things that we decided to do and recommend, are the things we decided not to do/recommend.

Probably the most obvious thing that the EDS 1.0 software excludes is an "always use this IdP, don't ask me again" feature. The reasons for removing this feature are:

There was no real way to allow the user to undo this choice. The EDS itself couldn't provide a link since, once the option was active, the EDS became invisible to the user.
SPs and IdPs couldn't provide a link since they may work with more than one EDS, and thus not know where to send the user. Even for those that only worked with one EDS, sending the user to that system would interrupt the log in flow and leave the user stranded at a EDS page that had no idea that an authentication event was in progress.
Since the EDS is embedded in each SP, such a feature would probably not have the effect the user expected. It would become a "don't ask me again for this SP" feature.
It changes the user experience from one visit to the next, so the experience becomes inconsistent as the user goes from service provider to service provider.

3 Implementation Details

3.1 Embedded Discovery Service (EDS)

The EDS will consist of two Javascript files and a CSS file. Installation of this EDS will require the deployer to link the Javascript files and CSS file in to the page that will contain the IdP selection windows and add a <div> with a particular ID.

In order to get the data needed to render the IdP selection the SP-side will consume a JSON file (described below). A new endpoint for the Shibboleth Service Provider is being developed that will produce the JSON file its loaded metadata.

3.3 JSON Data Structure

As mentioned above the Centralized and SP-side IdP selection UIs are driven by a JSON data file. JSON, instead of the SAML Metadata, was chosen for the following reasons:

the Javascript DOM level 3 APIs are not well supported on all browsers but are required when working with SAML metadata
SAML metadata contains a lot of information that is not necessary for rendering the UI
JSON files, on the browsers tested, parsed at least two orders of magnitude faster than the SAML metadata (due in large part because of the previous two reasons)

The JSON data file is described by this json_schema.json.

3.4 IdP Authentication/Consent Page

TODO

3.5 Associated Metadata Changes

In order to carry data such as localized names and descriptions for entities, as well as data which may be used for hinting, a set of metadata extensions will be used.

4 From Here to There

Clearly, the changes recommended above cannot be accomplished over night. They require thousands of organizations to make various changes to their web sites. While the SP, Centralized DS, and IdP software packages will bundle pieces of code to make these changes easier, it will still take time. Therefore, the Shibboleth Discovery Service software will enable the following transition options.

4.1 Centralized Discovery Service (CDS)

The new centralized Discovery Service 2.0 package will ship with an interface that matches the recommendations above. Therefore, all existing service providers which support either the legacy Shibboleth WAYF protocol or the standardized SAML Discovery Service protocol will be able to use this new version of the discovery service. This allows the immediate introduction of the new visual elements to their users. Federations which host a centralized discovery services will be able to deploy this and, as a result, cover most of their service providers (all those that don't have their own, home-grown, discovery solution).

It is important to note, however, that the use of a centralized service does NOT allow the CDS to look like the SP to which the user is attempting to authenticate. Therefore, there is still the additional, jarring, UI change from the SP to the CDS in addition to the one from the SP to the IDP.

4.2 Centralized JSON File

Some sites may wish to quickly adopt the locally hosted IdP selection interface, but may be unable to upgrade their service provider to a version that is capable of generating the JSON file that powers this interface. Therefore, the new Shibboleth centralized Discovery Service will provide an endpoint from which a site can periodically download the JSON file. This allows the site to locally host the static file and deploy the Site-embedded Discovery Service.

It is important to note that such sites are responsible for keeping the static JSON file fresh. Otherwise, new identity providers will not show up in the list and retired ones will not go away. If a service provider is a member of multiple federations, the JSON files from each federation can be easily concatenated together.

Related Reading

The following documents provide are usability studies performed by the UK and Danish federations: