Mind the Gap!

By Mikkel Hald, 18/05/21

Mind the Gap is WAYF's version, very lightweight, of the RA21 button (the recommended standard for laying out federated access on service provider websites). Any service provider offering federated access is encouraged to use it with his/her website.

Mind the Gap, simply a HTML file, is used as an iframe hosted on the service provider. It creates and sends the SAML authentication request and keeps track of which identity provider the user has selected.

Mind the Gap requires:

  • the service provider to be able to receive unsolicited responses;
  • the availability of a discovery service;
  • and the availability of a MDQ server for federation metadata lookups, to be able to show the display name of the selected identity provider.
Paths to WAYF's MDQ and discovery services are embedded in the Mind the Gap HTML file, easily modifiable into non-WAYF values if needed.

The service provider must accept either standard SAML or one of the simpler ways of handling SAML that WAYF offers: SAML2jwt or: SimpleSign with Ed25519ph keys. If SAML2jwt is used for connecting to WAYF, the required support for unsolicited responses is trivially present.

The simplest use of Mind the Gap is as an iframe, as it can act as the return page for discovery requests, and thus automatically keep track of the selected identity provider in localStorage on the service provider's domain. Mind the Gap supports sending a use=default parameter to the discovery service to allow the selection of the user's default identity provider even if it is unable to show the actual name of the identity provider on the user's very first visit to the service provider.

Mind the Gap is used like this (in the HTML source of the service provider's website):

<iframe src="/mindthegap.html?sp=<service provider's entityID>" style="width: 350px; height: 100px;" frameborder="0"></iframe>

There are additional optional parameters:

  • acs: the AssertionConsumerService URL, i.e. the location where the identity provider should return the SAML response; if not provided, the default ACS URL in the service provider's metadata is used;
  • RelayState: a string encoding relevant state information in the service provider that will be returned with the login response, cf. the SAML standard;
  • color: the button background color.