In SAML federations the SP application needs to find out where to send the end-user for authentication. This is called discovery, there are two ways to achieve it, and doing both is recommended:
- Use a discovery service such as OpenAthens Wayfinder
- Support 'WAYFless' URLs
The term 'WAYFless' comes from the old Shibboleth term for discovery: Where Are You From, and how to avoid having the end user interact with it by supplying the federation identifier for the user's organisation in the URL - e.g. https://sp.yourdomain.com/path?entity=https://idp.theirdomain.com/entity
Deep linking means being able to link directly to a specific page or article of the user's choice in your application that ideally passes through your authorisation process so that the end-user does not have to navigate away from that landing page to log in. E.g. a list of links to articles in a library portal.
Both are supported by Keystone and when combined make your application compatible with our redirector (a tool that allows the customer to put vanilla target links behind a consistent prefix and removes the need for proxy server masques in things like link resolvers).
Setting up WAYFless access
WAYFless access is supported with minimal configuration. The link is formed like this:
(essentially replace the '.oidc-app-v1.' part of your application's client ID with a slash for that middle bit)
This is not the prettiest link to present to your customers though however, the deep linking step can help with that.
Configuring in the publisher dashboard
On the Configuration tab, you will need to add the URL of your OIDC handler page (i.e. where your OIDC login is configured) in the Login URL field, so that connect.openathens.net, knows where to send the user afterwards.
Setting up deep link support
This requires you to add a little bit of code to your website/application to accept a target parameter (or extract one from the URI), store it in a domain cookie whilst the user is sent to connect.openathens.net, and then use your cookie to send the user where they need to go when they are returned to you.
Configuring in the publisher dashboard
You need to specify two things in the dashboard:
- Access the publisher dashboard at https://sp.openathens.net
- Access the relevant application record
To provide configuration for both places, you should:
- On the Linking tab, add a tokenised application link and domain - e.g.
URL (based on our example):
- If not already set, on the Configuration tab set the Login URL to be the URL of your OIDC handler page. This enables the WAYFless routing to work and is necessary.
- Click on done and then save.
This section only applies If you have an OIDC instance that supports 'OpenID Connect Dynamic Client Registration', and assumes a deeper understanding of how OIDC works. If you're not sure about either of those, stick with the basic method outlined above as that will work either way.
If you do have an OIDC instance that supports 'OpenID Connect Dynamic Client Registration' a target URL can be passed directly to the connect service (reference: 3rd party initiated login in the OIDC specs linked at the end). Your OIDC instance will receive it as the 'response' from /login, at which point you will need to store the target parameter for later use as the subsequent OIDC authorisation call to /oidc/auth does not support it.
This approach is great if you are already (or expect to be) using it with other OIDC providers.
The format for the deeplinking Wayfless URL would be :
You would also set the Login URL on the configuration tab to point to the address on your site that will store the target parameter, usually the OIDC handler page. The target will be passed now as
The flow is different and becomes:
- User follows link to connect.openathens.net for authorisation (OpenAthens stuff happens)
- User is sent back to the Login URL with a URL in the target_link_uri parameter.
- You store that URL as a cookie or similar
- OIDC redirects to connect.openathens.net/oidc/auth
- OpenAthens stuff happens again
- User returned with claims
- You authorise and pass to the stored target URL.
Whilst this means you do not have to deal with the enity parameter yourself, you have to read and store the target parameter in-between the OIDC authentication and authorisation calls - i.e. within the OIDC handler page itself.
For further information see: https://openid.net/specs/openid-connect-core-1_0.html#ThirdPartyInitiatedLogin