Configuring Evergreen ILS as an authentication provider for OpenAthens

Path to function: Management > Connections > Add > Evergreen ILS

Using the OpenAthens local authentication API, you can authenticate users based on credentials stored in any system to which you have programmatic access. This method is ideal in situations where you cannot use other connection types. Evergreen ILS has a built-in handler for our API.

Preparation

Before you start, you need:

An API key you have generated for this purpose. See API keys
Access to the OpenAthens administration area at the domain level
Access to your Evergreen administration portal

If you need technical help, consult the Evergreen documentation or your IT team. Our support team are also happy to help, but can fully support only the OpenAthens end of the connection.

Add the connection in OpenAthens

Log in to the OpenAthens admin area as the domain administrator.
Go to Management > Connections.
Under Local authentication in the left sidebar, press Create. A pop-up opens, showing available types of connector.

Select Evergreen ILS and press Configure.
In Display name, enter a name for the connection. You can edit this later.
(Optional.) Enter a description of the connection in the Description field.
Enter a Callback URL. Assuming defaults, this will be along the lines of https://<HOSTNAME>/eg/opac/sso/openathens, where <HOSTNAME> is the public hostname of your Evergreen installation. You may need to modify the path to suit your instance.
Press Add. The connection is created.

Details of a local connection called 'Evergreen'. They include the fields 'Display name', 'Connection ID', 'Connection URL', 'Callback URL', 'Status', 'Create local accounts' (which can be set to 'automatically' or 'manually'), 'Remove local accounts' (after a specified time period), 'Salt value' and 'Organization mapping'. At the top of the page is a button labeled 'Save changes'.

Detail fields

Field	Explanation
Display name	Name of the connection, as it will appear in our authentication point when there is a choice of connector.
Description	Description of the connection, as it will appear in our authentication point when there is a choice of connector.
Connection ID	The connection ID that must be specified in the API call payload. Pass this to your IT team before they begin implementation.
Connection URI	The domain specific URI where the API will be expecting the POST. Pass this to your IT team before they begin implementation.
Callback URL	An address in your site or application to which users will be sent for authentication. See Implementing the API connector in your code.
Status	Not Live = connection can be used only in debug mode. The visibility and default flags are ignored. Live and Visible (if this is the only local connection) = connection can be used only in debug mode. Live and Visible (if there are multiple live and visible connections) = users are offered a choice of connections, including this one. There is a domain preference to include OpenAthens accounts or not. Live and Visible and Default = this is your only login option and users will be sent directly to your login whenever the organisation is known. A successful authentication tells the authentication point to remember that location. A failed authentication clears the location preference. Debug mode will not show other login options. Changes to status usually take effect within a few minutes.
Create local accounts	Automatically: any user authenticated by your system and passed back to us is deemed OK and will be accepted by the system. Manually: only user IDs you have previously uploaded via the list page will be accepted by our systems. Unlisted users will be denied access and you will see organisation mapping errors in the reports interface.
Remove local accounts	This setting controls when local account data will be automatically cleared from the system and is the number of days from the last time the account last signed in. Pre-mapped accounts that have not been seen are also cleared. The setting can be from 1 to 365 days and represents the number of complete days that have passed since the date the account last signed in, i.e. does not include the day of the last sign-in in the count. See also: How to modify a local account.
Salt value	The salt used to generate a targetedID for users authenticated by this connection. You might edit the salt if upgrading from something like Shibboleth, so that your users can have the same targetedID value when they change systems. If you set it to blank, the connection will use the same salt as your OpenAthens accounts. Avoid modifying the salt after you go live, which will change the user identifiers seen by service providers.

Make note of the Connection ID and Connection URI. You will need these, along with your API key, to configure the Evergreen end of the connection.

Configure Evergreen

To set up your connection at the Evergreen end, see Evergreen’s guide to configuring sign-on to OpenAthens.

You will need the following information:

Your 36-character API key
The connection ID (copy from the Details tab in OpenAthens)
The connection URI (copy from the Details tab in OpenAthens)

Back in OpenAthens: configure mappings and permission sets

The final two areas to configure are permission set rules and attribute mappings:

Permission set rules so that your users are assigned an appropriate set of resources
Attribute mappings so that OpenAthens can make use of data passed it by your source.
OpenAthens will cache these attributes when the user signs in, so changes at your end won't be picked up until the next time the user starts an OpenAthens session

Both of these functions can only look at data in the attributes array you pass.

When you're ready to go live, go to the Details tab of the connection and set the Status to Live and Visible. Save your changes. Your new connection should be available in the authentication point in a few seconds.

How to test

Discovery is not available until you set the connection as Live and Visible, so that users do not get offered options that are not ready to be used. To test your connection before going live, you will need to use debug mode to make the connection selectable by you.

Once you have tested and are happy, you can set the connection as Live, Visible and optionally Default (where available), then save. This will make it live for your users within a few seconds.

Multiple connectors and OpenAthens accounts

This type of connector is best used as the default connection. In this mode, when a user arrives at our authentication point with your organisation known, such as would happen if they select it at a resource's login, use a WAYFless URL, use the Redirector or have previously authenticated successfully, they are passed directly to your login without seeing our authentication point.

If you need to use multiple connections, or OpenAthens accounts alongside local accounts - e.g. if you have a group of users that are not in your directory - then you can set the connection as Live and Visible but not Default, and set it to allow OpenAthens accounts via the setting on the domain preference page. In this mode, when the user arrives at the authentication point with your organisation known, they can select the connection they want to choose from all Live and Visible local connections as well as OpenAthens accounts. The authentication point remembers their choice for next time.

Screenshot. Under the heading 'Choose how to sign in' is a list of options - 'Staff', 'ADFS connection name', 'OpenAthens LA' and 'OpenAthens'.

Multi-valued attributes

With multi-valued attributes, such as the memberOf field in ADFS, the interface is unable to display all values and will display only one. However, all values are read and cached, so are available for functions like permission set rules and attribute release.

Anything to watch out for?

If you are planning to pre-upload user identifiers, you will need to have at least one local account visible in the list to access the upload button. Do not delete all your test logins until at least some of your pre-mappings are uploaded.