There are three parts to a basic integration:
Install an OpenID Connect plug-in or framework
- If you do not already have an OIDC plug-in or framework installed, find one for your platform and install it. This must support "OpenID Connect" specifically, rather just OpenID (which is older and will not work with OpenAthens).
- Configure your site to use the plug-in or framework and add the option to your login page alongside any other login methods you have. For help with that you will need to consult the documentation of your plug-in and platform.
Configure the basic application in the OpenAthens publisher dashboard
- Access the publisher dashboard at https://sp.openathens.net
- Add a new application, choosing OpenID Connect from the options
- Fill in the form
- All the fields on the first page can be changed later if necessary, but must be valid to proceed.
- Select a new connection unless you are sure you have another suitable one
- Click the create application button
- This will create the record and display the details you need to configure your OIDC plugin
For a detailed view of these 5 steps, see: Adding a new OIDC application to the publisher dashboard step by step
Configure your OpenID Connect plugin or framework for OpenAthens
- Access the configuration of your plugin or framework and update the settings to connect to OpenAthens.
- (a) and (b) below are always needed. Some or all all of the others may need to be specified. There can also be some small variation in terms:
- Client ID & Client secret or key - copy both from the dashboard > application > configuration tab
- Provider URI -
- Login or Authorisation endpoint -
- Token (validation) endpoint -
- User Info endpoint -
- JWKS / Key URI -
- Identity key / claim / attribute - this should usually be set as 'sub' (as in subject)
- Your plug-in or framework should support automatic configuration in the background, but if you need to specify the address manually (or check any of the content) it is https://connect.openathens.net/.well-known/openid-configuration
Additional configuration in the publisher dashboard
This comes in two halves - the application, which configured how your OIDC implementation talks to OpenAthens, and then the connection, which is the part that controls how you appear in SAML federations such as OpenAthens, InCommon, SWITCHaai and UK Access Management federation (accounts from your own domain will work whether or not you go live in any federations).
After you select your application from the list there are three tabs:
- The description and logo will appear for OpenAthens federation IdPs and would become mandatory when you wanted to go live in the OpenAthens federation
- The access URL will also become mandatory when you want to go live. During development it can be anything, but for the live service it would need to work. See: Access URLs
- This is where you define the format used for deep linking to specific pages in your application. See: Access URLs
- The settings controlling how your OIDC instance communicates with us:
- Client ID and secret should be copied to your OIDC configuration. They are both unique to your application and are used for secure communication with us
- Application URL is the root address of your application - e.g. https://www.myapplication.com.
- Redirect URL is where we should return the user afterwards. If you are unsure, enter the same root address - the address you want will become apparent later when you test and receive an invalid redirect url error.
- Login URL is the URL which will initiate a user login in your OIDC application. If not provided, Keystone will send users to your Redirect URL. A URL is required for WAYFless access and deep link support.
- Connection offers you a choice of existing connections to use with this application. If you are unsure, leave it as is.
- Discovery method allows you to choose between a default entityID (defaults your own) or a central discovery service. It defaults to OpenAthens Wayfinder, which is a very good choice if you are going to be in one or more federations.
- Entity categories allow you to restrict the entities that appear supported discovery services such as Wayfinder. If set, only entities that have matching categories in their metadata will appear.
- From the Connections page, select your connection. It will have the same name as you originally gave your application, and is also accessible from the application's details.
- After the list of applications using this connection are the mapping rules
- The standard mappings will usually be sufficient to translate the standard SAML attributes that the Identity Providers in the federation are sending to standard OpenID Connect Claims. You should not need the 'Standard OpenAthens' mapping.
- If they are not quite what you expect - for example email addresses are almost never sent by default - there are options to map and transform attribute names and values then apply them to a connection. See: Mapping SAML attributes to OIDC claims
- Next are the OpenAthens specific settings
- Enable access for your own OpenAthens accounts (Allow sign-in for your domain)
- Join the OpenAthens federation (Allow sign in by any OpenAthens domain - you still have control over who can access your application).
- Finally there are several other federations from around the world you can select.
- Selecting them only makes them available to your connection, it does not add you to their metadata and you will still need to join each federation you want to participate in.