If you have a built-in discovery service or a home realm discovery service, you might use it in conjunction with OpenAthens Wayfinder. Wayfinder gives you access to the institutional discovery functions that some systems lack, enabling users to select their organization from a preset list of federated institutions. (See OpenAthens Wayfinder UX.) The disadvantage of this combined setup is that users might need to go through discovery twice, first through your own discovery service and again through Wayfinder.
To avoid unnecessary repetition, Wayfinder enables users to bypass institutional discovery as long as the following conditions are met:
-
Your discovery service passes information with which Wayfinder can uniquely identify the user’s institution
-
That institution exists in Wayfinder’s database
In this situation, there is no need for further institutional discovery. The user is automatically passed to the next stage of authentication without needing to interact with Wayfinder.
If Wayfinder does not recognize the institution, or if the user’s details potentially match more than one organization, then the user cannot bypass institutional discovery. They are taken to the Wayfinder discovery page to select their institution.
For the bypass process to work, your discovery service must pass the standard OpenID Connect (OIDC) parameter login_hint, containing the user’s email address as its value. Wayfinder handles the rest.
Authentication process, bypassing Wayfinder
-
A user follows a link or path to one of your resources.
-
Your discovery service prompts the user to enter their institutional email address.
-
Your OIDC client sends an OIDC authentication request to
connect.openathens.net, passing the user’s email address as the value of the parameterlogin_hint. (For more about this parameter, see the OpenID Connect specification.) -
Wayfinder receives
login_hint. From the user’s address, it extracts the email domain. -
If the user’s email domain uniquely matches an institution that Wayfinder recognizes, Wayfinder automatically redirects the user to their institution’s SAML identity provider (IdP).
-
After the user successfully authenticates with their IdP, they are passed back to your service for authorization.
What if Wayfinder doesn’t recognize the email domain?
If Wayfinder does not recognize the email domain, it takes the user to a standard Wayfinder discovery page and tells them that no matches for their institution were found. The user can then try to search for their institution. The domain name passed by login_hint is pre-loaded into the search field.
What if the email domain matches more than one institution?
If there are multiple matches for the domain name, Wayfinder takes the user to a standard discovery page that displays a list of the matching institutions. The user can then select the institution to which they belong.
Configuration
The bypass function in OpenAthens Wayfinder is available by default. You do not need to configure anything in Wayfinder.
In your discovery service, ensure that:
-
Your OIDC client is configured to pass the
login_hintparameter. This typically happens by default -
login_hintis populated with the user’s email address (its default value), rather than with an alternative identifier