WAYFless access and deep linking in OpenAthens Keystone

Introduction

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. https://sp.example.com/path?entity=https://idp.them.example.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.

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:

https://connect.openathens.net/YOUR_OPENATHENS_API_NAME/APPLICATION_ID/login?entity=CUSTOMERS_FEDERATION_ENTITY_ID

E.g: https://connect.openathens.net/example.com/1667g24k-2a82-4928-a72b-777dja6do9a2/login?entity=https://idp.generic_customer.edu/entity

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

// using a parameter at e.g. www.example.com/deeplink?entity={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");
    header("Location: https://connect.openathens.net/YOUR_OPENATHENS_API_NAME/APPLICATION_ID/login?entity=${entity}");  
    
	exit;
 
// 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, in a separate field, the internet domains you own that it applies to. 

1. Access the SP dashboard at https://sp.openathens.net
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. Link syntax field (tokenised URL):

      1.     https://sp.example.com/deeplink?entityID={entity}&target={target}

   2. Service domains field (internet domains where the link syntax above will work): 

      1.     .example.com

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.

When specifying domains in the service domains field, the system will automatically wildcard them, so if you want to exclude any subdomains you will need to specify all the ones to include. e.g:

sub.example.com
img.example.com

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

.example.com
.example.net

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

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

Next step

Getting production ready with Keystone

Advanced