Path to function: Management > Connections > Add > ADFS
OpenAthens can connect to ADFS (Active Directory Federation Services) 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 ADFS login.
Before you start you will need:
If you are migrating from an alternative IdP such as Shibboleth, also see: Migrating from your own IdP
The following section assumes you are familiar with ADFS, If you are not, the next three steps have an alternative more detailed guide available.
Depending on your library's needs, this may be sufficient however you will usually want to release more information so that claims can be mapped to OpenAthens attributes and used for organisation, statistics, resource access, display names and resource allocation - e.g:
In all cases, the library will need the name of the claim for the next part of the set-up. Claim names are case sensitive.
Example Issuance transform rule:
AD will truncate sAMAccountName before release if it is over 20 characters. This may affect your choice of unique user attribute.
In the administration interface as the domain administrator, go to Management > Connections
(If you already have ADFS visible as a SAML connection, you will need to delete that connection before the system will allow you to add it back)
|The name of the connection as it will appear at our authentication point when there is a choice of connector. Defaults to the name specified in the ADFS metadata|
|Where the ADFS metadata is published. Populated only when metadata is loaded from a URL, it allows easy updates to the connection if your ADFS system changes.|
|The entity identifier of your ADFS instance, typically http://YOURDOMAIN/adfs/services/trust. Drawn from the ADFS metadata.|
|The login address, typically https://YOURDOMAIN/adfs/ls/. Drawn from the ADFS metadata.|
|Display name attribute||The claim you specify here supplies the value displayed in account lists and audit where you would normally see the OpenAthens username. DisplayName is a common source but it does not have to be different from the Unique user attribute claim.|
|Unique user attribute|
The claim you specify here must supply a 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. ObjectGUID is a popular choice.
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.
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
|Remove local accounts|
The salt used to generate a targetedID for users authenticated by this connection.
You might edit it if you were migrating from something like OpenAthens LA to MD 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 MD accounts.
Modifying this after you go live will change the identifiers seen by service providers for your users... which is rarely desirable.
The final two areas to configure are permission set rules and attribute mappings:
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.
Certificates - allows you to add a second certificate. Used when you need to change a server certificate on AD and want to minimise downtime for your users.
Advanced - Allows you to switch between SAML versions should you need to, and toggle signing of authentication requests (SHA-1 or SHA-256). Changes to the defaults are rarely necessary for this connection type.
Anything to watch out for?
When you use the refresh metadata button it will update everything in the connection with values from the metadata including endpoints, names and certificates. This will also undo any manual changes you have made on the advanced tab. The metadata URL can be removed to guard against this if you choose.
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.