Skip to main content
Skip table of contents

WAYFless access and deep linking in OpenAthens Keystone


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:

  1. Use a discovery service such as OpenAthens Wayfinder
  2. 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.

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.

WAYFless access and deep linking are very popular with our mutual customers and you should support both where possible.

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, 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, and then use your cookie to send the user where they need to go when they are returned to you. 


// using a parameter at e.g.{entity}&target={target}
    $target = $_GET['target'];
	$entity = $_GET['entity']; 

	// set a target cookie
    $cookie_name = "deeplink";
    $cookie_value = "${target}";
    setcookie($cookie_name, $cookie_value, time() + (60 * 5), "/"); // Five minutes should be more than enough
	// Send the user to the Wayfless link
    header("Status: 302 Temporary move");
// after the user is returned to your OIDC handler page
// and at the appropriate place in your authorisation flow
	// read the cookie  
    $cookie_name = "deeplink";
    // Send the user to the page in the cookie, e.g:
    if(!isset($_COOKIE[$cookie_name])) {
        header("Location: ./DEFAULT_LANDING_PAGE");
    } else {
        header("Location: $_COOKIE[$cookie_name]");

Configuring in the publisher dashboard

You need to specify two things in the dashboard - a link syntax with a couple of variables, and the internet domains you own that it applies to. 

  1. Access the SP dashboard at
  2. Select your application
  3. On the Linking tab, add a tokenised application link and domain - you can use whatever parameter names you need to, but the tokens must be {entity} and {target}. e.g.
    1. URL:

    2. Domains: 
  4. 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.  
  5. Click on done and then save.

Whilst you can rename the parameters used for 'entityID' and 'target' in step 1 to suit your code, the 'entityID' parameter you pass to the address must be 'entity', and the two tokens in the URL specified in the linking tab must be '{entity}' and '{target}'.

The system will automatically wildcard any domains you enter, so if you want to exclude any subdomains you will need to specify all the ones to include.

Multiple domains can be specified if necessary - e.g.

The leading dot should be included in case your domain should happen to match the tail of someone else's domain - e.g.  could clash with where would not .


You must not include domains that you do not own - they may be removed without notice.

Next step

Getting production ready


Click to expand the advanced section

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.

I understand. Show me

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 :{entity}&target={target}

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 target_link_uri.

The flow is different and becomes:

  1. User follows link to for authorisation (OpenAthens stuff happens)
  2. User is sent back to the Login URL with a URL in the target_link_uri parameter.
  3. You store that URL as a cookie or similar 
  4. OIDC redirects to
  5. OpenAthens stuff happens again
  6. User returned with claims
  7. 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:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.