Embedding OpenAthens Wayfinder

Wayfinder can be embedded into your site if you are using OpenAthens Keystone. Which is kinda cool.

Get the code from the service provider dashboard

Sign in to the service provider dashboard (https://sp.openathens.net).
Go to Applications > select your OpenID Connect application > Discovery tab.
Scroll to the discovery method section and select the radio button for Wayfinder.
In the Authorised domains field, add the internet domain(s) where you will be using Wayfinder (e.g. *.yourdomain.com)
Click the link How to add Wayfinder to your web application. A pop-up opens, showing JavaScript code.
Copy the JavaScript.

The code is tied to the specific Keystone application since Wayfinder needs to know where to return the user. If you need to support multiple apps from a common login page you will need to find a way to insert the relevant oaAppId (coloured red in the interface).

Add the code to your website

Paste the JavaScript into the <HEAD> of the page (or site if necessary).
The code can be invoked by two methods:
1. If you want Wayfinder to appear as an overlay, use the wayfinder-login selector in the trigger - e.g:
  <a href="javascript:;" class="wayfinder-login">Institutional login</a>
2. If you want Wayfinder to appear embedded in a div, use the wayfinder selector, e.g:
  <div id="wayfinder">Loading...</div>
  You should not set a height on the div or search results may overflow the available space.

If neither selector is found on the page, no error is displayed to the user but one is sent to the console. If both are on the page then the wayfinder selector will be used (embedded).

Which should I choose?

It's up to you of course, but we would suggest that where your login function is in a small area of a regular page then the overlay is probably the better choice as searching for organisations can produce several answers. If your login function is on a dedicated page then the div version may fit in better with the UX and style. Both will allow you to customise the labels - see the advanced options section below.

When testing, try some terms that will produce many results (such as University) and use the show more results button.

Federations

The OpenAthens federation will be updated automatically but if you are in any other federations they will have to update your metadata to include valid discovery return URLs before Wayfinder can work for you:

XML

<idpdisc:DiscoveryResponse Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="http://connect.openathens.net/saml/2/auth" index="1"/>

Advanced operations

Some advanced information for anyone who needs a little more control

See the information

Logic flow

_wayfinder.options

These allow some changes of behaviour - add them to the end of the script block you got from the dashboard - e.g:

Example

CODE

<script>
    (function(w,a,y,f){
	...script block from service provider dashboard...
         )(window,document,'https://wayfinder.openathens.net/embed/','/loader.js');


    _wayfinder.options = {
        trigger: '.pre-existing-class',
		enableGeolocation: true,
		rememberCrossSite: true,
		ui: {
            titleText: 'Find your institution',
            summaryText: 'Your university, company or library',
            placeholderText: 'Institution name or email...',
            previousSearchUITitleText: 'Search for your institution',
            previousSearchUISummaryText: 'Institutions you\'ve selected before',
            previousSearchUISearchAgainText: 'Search for another institution...',
            previousSearchUIDeleteResultsText: 'Delete institution'
        }
    }
</script>

The options currently available are:

N

Type

Notes

trigger

String

If you do not wish to use the default CSS selector name you can specify an alternative target or trigger (not both).

target

String

enableGeolocation

Boolean

If omitted, or has any value other than true, geolocation hints are disabled.

rememberCrossSite

Boolean

If omitted, or has any value other than false, selected organisations are remembered for and from selections at other sites

ui

Object

N	Type	Default text (en, en-GB)	Notes
titleText	String	Find your institution	When undiscovered / no remembered organisation
summaryText	String	Your university, company or library	When undiscovered / no remembered organisation
placeholderText	String	Institution name or email...	When undiscovered / no remembered organisation Appears in the search box
previousSearchUITitleText	String	Search for your institution	Where there are remembered organisations
previousSearchUISummaryText	String	Institutions you've selected before	Where there are remembered organisations
previousSearchUISearchAgainText	String	Search for another institution	Where there are remembered organisations
previousSearchUIDeleteResultsText	String	Delete institution	Where there are remembered organisations Appears in a button

If omitted or of zero length the default is used. If your text includes quote marks or apostrophes they will need to be escaped.

The default text will use any relevant localisations we have uploaded.

buttonOptions

Object

N	Type	Default setting	Options
size	String	'medium'	small

More options may become available in the future.

About Geolocation

Geolocation can help users select the correct organisation when none are shown, but means the browser will ask for permission when it hits any page with the Wayfinder JavaScript in the head. If Wayfinder will appear on multiple pages we recommend leaving this function disabled.

About rememberCrossSite

The default and recommended mode is to allow the organisation selection a user made elsewhere using Wayfinder to be reflected in your instance (and also the organisation selection made in your instance available elsewhere). This provides the best user experience, however you can turn it off with this option if you need to limit it to just remembering choices on your site - e.g. if the users commonly need to use a different IdP to access your site.

Customising the appearance

Retaining the default appearance of the embedded Wayfinder is encouraged as this provides a consistent user experience across sites (one of its goals). If you must change the appearance (such as when the colours clash with your brand), then you can override the styles for some key classes in your CSS. Here is an example:

Overlay button

The overlay version is invoked by a button which has three possible appearances and uses the .wayfinder-button class. The third one is for when Wayfinder remembers a user's previous selection, and has a .active class. Let's use three shades of blue in our example:

Overriding the colour of the embedded Wayfinder button

CSS

.wayfinder-button {
    background-color: #007bff !important;
}
 
.wayfinder-button:hover,.wayfinder-button.active:hover {
    background-color: #007ba8 !important;
}
 
.wayfinder-button.active {
    background-color: #0014ff !important;
}

(The !important bit is to ensure you override the default appearance.)