Configuring Okta as an authentication provider for OpenAthens

Path to function: Management > Connections > Add > SAML

OpenAthens can connect to SAML sources including Okta 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 Okta login.

Preparation

Before you start, you will need:

Access to the OpenAthens administration area at the domain level
Access to your Okta admin dashboard

If you're unsure about anything or get stuck, we're happy to help but can't really support other people's software. Hit the support link in the top right of the admin area to get through to your local support team.

Start in Okta

In the Admin section

Go to Applications and add a new application
You'll need to create new app
In the dialog box:
1. Platform: Web
2. Sign on method: SAML 2.0
App name: OpenAthens is a good choice, but it could be anything.
App logo (optional)
App visibility (up to you)
NEXT button
Single sign on URL – enter placeholder text for now, any URL with a valid format will do, for example https://placeholder.com
1. (this is because the data you need isn't generated until you register the app in OpenAthens, which requires something that isn't available until this wizard is finished. We'll come back and change this later)
Audience URI (SP EntityID) – enter the same placeholder text here too
Default RelayState: leave blank
Name ID format: This needs to match the format of what you will be sending as the username.
1. If your usernames are email address, you must select that option, otherwise select 'persistent'.
Application username: Okta username is usually fine. If picking something else, it must be unique to the user
Advanced settings – leave them all alone, you don't need to change any
Attribute statements:
1. Name is what it is sent as and you will enter at the OpenAthens end, e.g. ‘email’. Leave the format as unspecified unless it's an email.
2. Value is where you select the data to send, e.g. ‘user.email’
FINISH button
Copy the metadata URL (at the time of writing it looked like this)

Basic setup in OpenAthens

In the administration interface as the domain administrator go to Management > Connections

Click the add button on the left and select SAML from the options
Paste in the metadata URL you copied from Okta.
Set both the user identifier and display name fields to Use Subject NameID. We can change the display name later if necessary.
Do not set it as default at this time.
Save changes. You should now have a page that looks something like this:
Go to the Relying party tab and copy the metadata address. This is unique to this connection.
Paste that metadata address in a new tab and go there. You'll need some data from that to replace the placeholders you put into Okta

Back in Okta

Change from the Sign on tab to the general tab
Scroll down to the SAML settings section and click the edit button
Click next to get past the first screen
Update the placeholders you entered originally:
1. Single sign on URL: near the bottom of the relying party metadata you opened up a moment ago, find the line that says AssertionConsumerService. You need the location URL from that line (between the quotes where it says Location=). The line will look like similar to this:
  
  <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.openathens.net/saml/2/acs/YOURDOMAINNAME/la/NUMERIC_ID" index="1"isDefault="true"/>
2. Audience URI: Paste in the relying party URL you copied from the admin area – it’s the same as the entityID
NEXT button
FINISH button

This gets you to a place where you can test things are working at the most basic level.

If you are a new site with no active users, you can just set it as live, visible and default in the OpenAthens admin area. If you have users, actively using another connector or OpenAthens accounts, you will need to be a bit trickier to avoid confusing them - see: How to use debug mode

Final steps

Once you have tested the basics are working you can set things up to send any additional attributes.

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.

In Okta this is defined on the same page where you went back and entered the Single sign on URL and entityID in the attribute statements section. Make a note of the names you assign them as you will need to enter those at the OpenAthens end.

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.

Changes to these rules take only a few seconds to go live.

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.

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.

Understanding the connection page

Field	Explanation
Display name	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 SAML metadata
Metadata URL	Where the SAML metadata is published. Populated only when metadata is loaded from a URL, it allows easy updates to the connection if your SAML system changes.
EntityID	The entity identifier of your SAML instance, drawn from the SAML metadata.
SSO endpoint	The login address, again drawn from the SAML metadata.
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. If using the SAML NameID here, the requirement for unique and persistent limits the type to: `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
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 can take a few minutes to go into effect.
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.
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.

The other tabs

Certificates - allows you to add a second certificate. Used when you know the server certificate on the Otka end is about to change and you want to minimise downtime for your users.

Advanced - Allows you to make several changes that are not necessary in this case:

switching between SAML versions
switch the profile from Redirect to Post
enable signing of authentication requests (SHA-1 or SHA-256)
enable the SAML forceAuthn option (forces the local source to re-authenticate any time the user is sent there - e.g. where users can have multiple affiliations within a consortium and session management makes it difficult for them to change).