WAYFless access and deep linking in the OpenAthens Federation

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.

When combined, deep linking and WAYFless access make your application compatible with most discovery services, library management systems and link resolvers (e.g. EBSCO EDS, ExLibris Alma/Primo, OVID LInkSolver) via our redirector, which allows the customer to put vanilla target links behind a consistent prefix and removes the need for proxy server masques.

Setting up WAYFless and deep link support

How you do this depends on the way your site works and the federation technology you're using. If you're using OpenAthens Keystone, see: WAYFless access and deep linking in OpenAthens Keystone, which will take you through the rest of the process. 

For external applications, support can sometimes be as simple as passing entityID and target parameters to your SP instance but since the way those are tied into your systems can be very specific to how your service works, we regretfully have to direct you to the documentation of that software.

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.

If you include domains that you do not own they may be removed without notice.