Configuring OpenID Connect as an authentication provider for OpenAthens
Path to function: Management > Connections > Add > OIDC |
OpenAthens can connect to OpenID Connect (OIDC) sources such as Auth0, Azure, Google Workspace, and similar so that you do not have to issue personal accounts for your users (you will still need your OpenAthens administrator account).
As well as the ability to use local accounts instead of maintaining a separate set of credentials, accesses to federated resources that already involve discovery (identifying the users' home organisation) will take the user directly to your OIDC login.
Preparation
Before you start you will need:
Access to the OpenAthens administration area at the domain level
Access to the configuration of your OIDC provider
Your OIDC’s ‘wellknown’ config address. This will be available from your provider’s documentation if it is not in its admin interface.
An up-to-date OIDC provider
If you are migrating from an alternative IdP such as Shibboleth, also see: Migrating from your own IdP
If you're unsure about anything or get stuck, we're happy to help. Hit the support link in the top right of the admin area to get through to your local support guys.
Add the connection in OpenAthens
In the administration interface as the domain administrator go to Management > Connections
Click the add button on the left and select OIDC from the options
Enter the .wellknown address of your OIDC source.
The wellknown URL is typically something like https://serveraddress/.well-known/openid-configuration.
If the configuration is valid (see end) this will automatically fill in most fields:
You will need to add the client ID and secret. Your OIDC provider might not display those until you tell it about the 'relying party'. Get that address from the relying party tab - it is unique to the connection:
Once you have entered the client ID and secret, set the display name attribute and unique user attribute your OIDC provider will be sending - if you’re not sure what they are, set both to ‘bob’ for now so that you can save.
If you didn’t need to get the Relying party address already, go to that tab and make a note of the address so you can configure your OIDC provider.
You should now see something similar to this:
The detail fields displayed are
Field | Explanation |
|---|---|
Display name | The name of the connection as it will appear at our authentication point when there is a choice of connector. It defaults to the name specified in the wellknown confirg, so you’ll probably want to change it. |
Description | The description of the connection as it will appear at our authentication point when there is a choice of connector |
Configuration URL | The wellknown configuration address. If the configuration changes, you can use the refresh button to the right to reload it. |
Client ID | Sort of like a username your OIDC provider uses to connect to us |
Client secret | Sort of like a password that the client uses only with OpenAthens. Keep this one super secret. |
DIsplay name attribute | The attribute you specify here supplies the value displayed in account lists and audit. Something human readable is recommended. It does not have to be different from the Unique user attribute. |
Unique user attribute | The attribute you specify here must supply a persistent value unique to the user within the current user set and should supply a pseudonymous value unique to that user for all time. This is used by the system to tell users apart and also used in the generation of targetedIDs and statistics. It does not have to be the username entered at your login point. |
Status | Not live = connection can only be used in debug mode. The visibility and default flags are ignored. Live and visible (if this is the only local connection) = connection can only be used 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 & visible & default = This is your only login option and users will be sent directly to your login whenever the organisation is known. A successful authentication will tell the authentication point to remember that location. A failed authentication will clear that setting. Debug mode will not show other login options. Changes to the status usually take effect within moments. |
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 it if you were 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. Modifying this after you go live will change the identifiers seen by service providers for your users... which is rarely desirable. |
Add the OpenAthens information to your OIDC provider and configure attribute release
You will need to reference the documentation of your OIDC provider for how to configure it - it will often refer to this as adding an app.
The OpenAthens address to use for this is at the address quoted on the Relying party tab of the connection you set up in OpenAthens - it will look similar to: https://login.openathens.net/saml/2/metadata-sp/example.com/la/123456
If it asks for a login address as well, this will be for something usually known as IdP Initiated login which is where there’s an icon or link at your end to trigger things. If the field is not mandatory, leaving it blank is an option but the best URL to use is MyAthens as that will start a session somewhere useful. Ideally your wayfless version of the link (copy from the configuration section of MyAthens in the admin area - management menu > MyAthens), but https://my.openathens.net will work almost as well.
What to release
At a minimum you will need to release a unique user identifier. This identifier can be anything you like, but it must be persistent and unique amongst current users. Ideally it would be pseudonymous and unique for ever (i.e. never assigned to a new user).
Depending on your library's needs, the unique user identifier may be sufficient however you will usually want to release more information so that local attributes can be mapped to OpenAthens attributes and used for organisation, statistics, resource access, display names and resource allocation - e.g:
First and last names or a display name to help the library identify users (the unique user attribute shouldn't be suitable for this)
Email address to help the library contact users and, in certain cases release that data to service providers
An attribute indicating group membership to let them assign different permission sets to different groups of users based on rules
A department or OU name for statistics to aggregate on
In all cases, the library will need the names of the attributes for the next part of the set-up. Attribute names are case sensitive and may not contain spaces.
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 as assigned an appropriate set of resources
Attribute mappings so that OpenAthens can make use of data passed it by your souce
OpenAthens will cache these attributes when the user signs in, so changes in your directory won't be picked up until the next time the user starts an OpenAthens session.
When you're ready to go live, check both the live and visible boxes and then save. Your new connection should be testable a few seconds later.
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 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 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 at a resource's login, use a WAYFless URL, the Redirector or have previously authenticated successfully, they are passed directly to your login without seeing our authentication point.
If you have a 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 preferences page. In this mode when the user arrives at the authentication point with your organisation known, they will initially see a chooser where they can select the connection to use - all live and visible local connections will be available as well as an option to use OpenAthens accounts. The authentication point will remember their choice.
Multi-valued attributes
With multi-valued attributes - e.g. the memberOf field in ADFS - the interface is not able to display all values and only display one. All values are read and cached though so are available for things 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.
If your provider is old, it may not be compatible with current standards. Upgrading it to a newer version is usually sufficient.
Pseudonymous?
Pseudonymous identifiers are recommended for the unique user attribute to avoid potential problems with data protection legislation as that identifier will live on for a time in the audit trail after other mapped attributes are cleared.
.well-known validation
If your .well-known config fails validation, check that:
Issuer – present and uses https
authorization_endpoint – present uses https
token_endpoint – present uses https
jwks_uri – present and uses https
response_types_supported – supports ‘code’
id_token_signing_alg_values_supported – supports ‘RS256’ or ‘HS256’
scopes_supported – supports ‘openid’
token_endpoint_auth_methods_supported – supports at least one of ‘client_secret_post’ or ‘client_secret_basic’
grant_types_supported (optional) - if present, it must support ‘authorization_code’, if missing the default value is ["authorization_code", "implicit"] as per the OIDC discovery spec (https://openid.net/specs/openid-connect-discovery-1_0.html)