Path to function: Management > Connections > Add > SAML

OpenAthens can connect to SAML sources such as Azure, G Suite, OneLog, OpenAthens LA, Shibboleth,  and similar 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 SAML 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

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

  1. Click the add button on the left and select SAML from the options

  2. Enter the SAML metadata URL or upload the xml file representing your SAML source.

    1. The metadata URL is typically something like https://YOURDOMAIN/path/metadata and would need to be accessible outside of your network.

  3. Set the user identifier field to match the attribute you will be sending as the user identifier. This can be changed later, but needs to have a value to save the page.

  4. Set the display name to match the attribute you want to use - if you are only sending one attribute, 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.

  5. Do not set it as default at this time.

  6. Save changes

  7. Go to the Relying party tab and make a note of the metadata address - you will use this to configure your SAML source.

You should now see something similar to this:

The detail fields displayed are

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.


The entity identifier of your SAML instance, typically http://YOURDOMAIN/oala/metata for OpenAthens LA. Drawn from the SAML metadata.

SSO endpoint

The login address, typically https://YOURDOMAIN/oala/sso. Drawn from the SAML metadata.
DIsplay name attributeThe 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

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

Salt value

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.

Add the OpenAthens metadata to your SAML source and configure attribute release

You will need to reference the documentation of your SAML source for how to configure it to "connect to a service provider". There is help available for some of the more popular SAML sources including Azure and Google in our third party apps section.

The OpenAthens metadata to use for this is at the address quoted on the Relying party tab of the connection you set up in OpenAthens - it will look similar to: 

EntityID / Provider ID / ID

The same as the OpenAthens metadata address,


ACS / Association Consumer Service / Binding address / Reply address

Almost the same as the OpenAthens metadata address (change 'metadata-sp' to 'acs'),


Binding methodPOST

At a minimum you will need to release a unique user identifier. This identifier can be sent as 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, 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:

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.

Configure mappings and permission sets

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.

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:

Anything to watch out for?

When you use the refresh metadata button it will update the connection with values from the metadata including endpoints and certificates. It won't change the name or any options on the other tabs.

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.


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.