MDUI extensions: Recommendations for UK federation entities

The UK federation supports Metadata Extensions for Login and Discovery User Interface, known as MDUI extensions. These extensions allow the SAML software to present an improved user interface by displaying more information about, and logos for, your entity. This additional information may help users, particularly beginners, negotiate that all-important "first login" experience.

How to register MDUI elements

You should register DisplayName, Logo and (for SPs only) Description for each of your entities. Specific recommendations for SPs and IdPs are below.

To achieve this, the entity's administrative contact or a management contact for your organisation should send an email containing a request to update the metadata for the specified entity (or entities) to the UK federation helpdesk.

Please do not send image files; we do not include image files directly in the metadata. Please send https-protected URLs at which the appropriate images may be found on your server, along with the image sizes and any display text.

Recommendations for SP operators

SP operators should register one or two logos, a display name and description so that these can appear during discovery and login

DisplayName

This is a brief name for the service such as "Foobar Scientific Journals". It is shown in the default login page for the Shibboleth IdP. It should be a noun phrase, because it may be used by the software as such. For example: "You have asked to log in to Foobar Scientific Journals". It is also used as the "alt" name for the logo in both locations.

If a Description is not present, the DisplayName value is used in the default IdP login page to generate a description as described above ("You have asked to log in to DisplayName").

Logo

The mdui Logo is specified by its height and width and the URL at which it can be found.

The URL must be https protected (to avoid warnings from some browsers). The logo image should have a width of between 64 and 350 pixels, and height of between 64 and 170 pixels. The logo background (if any) should be transparent.

More than one logo URL may be provided, but in practice all that distinguishes them is size. If there is more than one logo then a larger logo might be used in preference by a discovery service and a smaller logo by an IdP login page, for example.

  • Please provide the logo's dimensions as well as its URL when you register it with the UK federation.
  • Please ensure that the logos used are .gif or .png files (as per the MDUI specification). Other formats (for instance .ico or .jpg) may work but can cause problems with some browsers.

Description

This is a short (100 character) description of the service, for example "Online access to all publications of Foobar Inc since 1892". It is displayed on the default login page for the Shibboleth IdP. Long descriptions will be truncated (precisely where will depend upon the browser).

InformationURL and PrivacyStatementURL

You may also wish to supply InformationURL and/or PrivacyStatementURL elements. The content found at the InformationURL should provide more complete information than what would appear in a Description element. The PrivacyStatementURL specifies a location for a privacy statement. Privacy statements are meant to provide a user with information about how information will be used and managed by the entity acting in a given role.

InformationURL is a mandatory element for SPs that assert the REFEDS R&S category.

The URLs provided in these elements should be https protected.

Recommendations for IdP operators

IdP operators should register one or two logos and a display name so that these can be displayed as shortcuts during discovery

DisplayName

This is the name which is shown to the user when interacting with the Discovery Service. It must match the IdP's OrganizationDisplayName. If you request a Logo but not a DisplayName then the technical team will register a DisplayName the same as the IdP's OrganizationDisplayName.

Logo

A logo is described by its height and width and the URL at which it can be found. The URL must be https protected (so as to avoid warnings on some browsers). You should provide two logos of sizes as follows:

  • One of width 80 pixels and height 60 pixels (approximately), with a transparent background. This is used by the discovery service.
  • A 16 by 16 pixels 'icon'. This is used by the Shibboleth EDS.
  • Please provide the logo's dimensions as well as its URL when you register it with the UK federation.
  • Please ensure that the logos used are .gif or .png files (as per the MDUI specification). Other formats (for instance .ico or .jpg) may work but can cause problems with some browsers.

Please note you should not host the logo on the servlet container (e.g. Tomcat). Such containers send a cookie with every request and any web page embedding such a URL will therefore be sending "third party" cookies.

DomainHint

This is a list of domains for which the IdP might be preferred. The RA21 project intends to use this element to allow users enter their email domain to hint at which IdP they should use. We are investigating (late 2017) the automatic population of DomainHint elements from the Scope of your IdP, but if the email domain you use is not the same as the Scope, then you should explicitly register the email domain.

IPHint

This is a list of CIDR blocks of IP addresses for which the IdP might be preferred. A University IdP might specify its campus IP addresses as IP Hints.

GeolocationHint

The geographical locations in degrees of latitude and longitude of places where one might find users of the IdP.

Localisation

All of the text elements can be provided with a language. Much of the software can exploit language variants.

  • If any of these attributes are provided, then an xml:lang="en" variant must be included.
  • If your users might benefit from different language entries, then these may be provided.

Example flow

MDUI elements are used in the following ways:

  • During discovery at the UK federation Central Discovery Service (formerly known as the WAYF), when a logo and user-friendly name for the SP can be displayed, providing continuity of experience
  • During discovery, the logos of previously selected (or otherwise recommended) IdPs can be displayed, providing easily recognisable short cuts for the user
  • During login at the IdP, the logo and user-friendly name of the SP can be displayed along with a brief description of the service. Again this provides continuity of experience.

You can see the use of mdui Logo, DisplayName and Description using the example of the UK federation test SP (with entityID https://test.ukfederation.org.uk/entity) in conjunction with the UK federation test IdP (with entityID https://test-idp.ukfederation.org.uk/idp/shibboleth).

You can inspect the metadata for these two entities: metadata for the UK federation Test SP and metadata for the UK federation Test IdP

To examine the flow:

  • Go to the UK federation test SP landing page Note the logo at the top.
  • Select "UK federation Central Discovery Service" to be redirected to the IdP selection page. Note that the SP Logo and Description appear on the IdP selection page
  • Select "UK federation test IdP". Note that the icon Logos for registered IdPs are displayed in the drop-down as you type.
  • Click the Continue button to be redirected to the IdP login page. Note that the SP Logo, DisplayName and Description appear on the login page.
  • Go back to the UK federation test SP landing page and select "UK federation Central Discovery Service" again. This will now show the DisplayName and Logo for the selected IdP.

Supported products

At the time of writing at least the following SAML software products may take advantage of mdui extensions: