Search

Skip to end of metadata
Go to start of metadata

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

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_DOMAIN/APPLICATION_ID/login?entity=CUSTOMERS_FEDERATION_ENTITY_ID

E.g: https://connect.openathens.net/yourdomain.com/1667g24k-2a82-4928-a72b-777dja6do9a2/login?entity=https://idp.bigpharma.com/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. 

pseudocode
// using a parameter at e.g. www.yourdomain.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_DOMAIN/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:

To provide configuration for both places, you should:

  1. On the Linking tab, add a tokenised application link and domain - e.g.
    1. URL (based on our example):

      1. https://oidc.yourdomain.com/deeplink?entityID={entity}&target={target}
    2. Domains: 
      1. .yourdomain.com
  2. 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.  
  3. 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 connect.openathens.net address must be 'entity', and the two tokens in the URL specified in the linking tab must be '{entity}' and '{target}'.

Next step

Getting production ready

Advanced

 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 :

https://connect.openathens.net/YOUR_OPENATHENS_DOMAIN/APPLICATION_ID/login?entity={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 connect.openathens.net 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  connect.openathens.net/oidc/auth
  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: https://openid.net/specs/openid-connect-core-1_0.html#ThirdPartyInitiatedLogin

  • No labels