OpenAthens can connect to CAS (Apereo/JASIG's Central Authentication Service) 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 CAS login.
Before you start you will need:
- A CAS server with SAML support enabled (v5.x or later)
- A member of your IT team to update CAS settings and supply the CAS metadata .
- Ideally an externally accessible URL for your CAS metadata, but failing that copy of the metadata as an XML file
- All users to be in CAS
- 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 CAS
- Enter the CAS metadata URL or upload the xml file as supplied by your IT team.
- The metadata URL is typically something like
https://HOST_NAME/cas/idp/metadataand would need to be accessible outside of your network if used.
- The metadata URL is typically something like
- Set the user identifier field to match the attribute you are sending as the user identifier. This can be changed later, but needs to have a value to save the page.
- Set the display name to match the attribute you want to use - if you are only sending one attribute or are not sure, you can set this the same as the user identifier. Again this can be changed later, but needs to have a value to save the page
- Do not set it as default at this time.
- Save changes
- Make a note of the metadata address displayed on the relying party tab
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. Defaults to the name specified in the CAS metadata|
|Where the CAS metadata is published. Populated only when metadata is loaded from a URL, it allows easy updates to the connection if your CAS system changes.|
|The entity identifier of your CAS instance. Drawn from the CAS metadata.|
|The login address, typically https://HOST_NAME/cas/idp/profile/SAML2/POST/SSO. Drawn from the CAS metadata.|
|Display name attribute||The attribute you specify here supplies the value displayed in account lists and audit where you would normally see the OpenAthens username. It does not have to be different from the Unique user attribute claim.|
|Unique user attribute|
The attribute 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.
If using the SAML NameID here, the requirement for unique and persistent limits the type to either of:
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
|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.
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.
Add OpenAthens as a service in CAS
The following section assumes you are familiar with CAS.
Register the address you copied from the relying party tab earlierin your CAS service registry - e.g:
- Set up your attribute release policy to release a unique user identifier which can be an attribute or the SAML nameID, 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, this may be sufficient however you will often want to release more information so that 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 to help the library identify users
- Email address to help the library contact users and, in certain cases release that data to service providers
- A group attribute of some type to let them assign different permission sets to different groups of users based on rules
- An attribute that would serve as a display name
In all cases, the library will need the name of the attribute(S) for the next part of the set-up. Attribute names are case sensitive.
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 available from your LDAP
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.
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.
The other tabs
Certificates - allows you to add a second certificate. Used when you need to change a server certificate on your end and want to minimise downtime for your users.
Advanced - Allows you to make several changes that are rarely necessary:
- switch between SAML versions should you have a source that can only handle the older SAML 1 profile
- switch the profile from Redirect to Post if your source insists on it
- enable signing of authentication requests (SHA-1 or SHA-256) if your source requires it
- enable the SAML
forceAuthnoption (forces your local source to re-authenticate any time the user is sent there - e.g. where users can have multiple affiliations within a consortium and your SAML source's session management makes it difficult for them to change).
Anything to watch out for?
The minimum supported TLS version is 1.2.
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.