Path to function: Management >Connections > Add > API
The OpenAthens local authentication API can be used to log your users into the system based on credentials stored in any system you can gain programmatic access to and is ideal in situations where you cannot use any of the other connection types. It requires you to implement some code at your end.
Your local systems should use at least two factor authentication (e.g. username and password, barcode and pin).
Before you start you will need:
- An API Key you have generated for this - see API keys
- A member of your IT team with web-programming experience
- Access to the OpenAthens administration area at the domain level
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 API
- Enter a name for the connection. You can edit this later.
- Enter a callback URL. This will be where users are sent to sign in if they do not already have an OpenAthens session when they attempt to access a resource - see implementing the API in your code for more detail. You can edit this address later.
- Save changes
You should now see something similar to this:
The connection ID and URI are specific to your domain and generated automatically. You will need to pass both of these values, and the API key you generated to your IT colleague.
The Salt value is used only if you are migrating from a SAML product such as Shibboleth or OpenAthens LA and is unlikely to be necessary if you are adding this type of connector.
The detail fields displayed are
|The name of the connection as it will appear at our authentication point when there is a choice of connector.|
|The connection ID that needs to be specified in the API call payload. Pass this to your IT colleague before they begin their implementation.|
|The domain specific URI where the API will be expecting the POST. Pass this to your IT colleague before they begin their implementation.|
|Callback URL||An address in your site or application that users will be sent to for authentication (see: Implementing the API connector in your code)|
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 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
|Remove local accounts|
The salt used to generate a targetedID for users authenticated by this connection.
Modifying this after you go live will change the identifiers seen by service providers for your users... which is rarely desirable.
Set up your application
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 source
Both of these functions can only look at data in the attributes array you pass.
When you're ready to go live, check both the live and visible boxes and then save. Your new connection should be available a few seconds later.
Anything to watch out for?
Minimum TLS version is 1.2.
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.