Skip to main content
Skip table of contents

Configuring Microsoft Azure as an authentication provider for OpenAthens

This section assumes a basic level of familiarity with the Azure interface (Entra ID). If necessary, ask your IT team to help set up and configure Azure.

While our service desk will always try to be helpful, they can only support the OpenAthens end of the connection.

Prerequisites

You will need:

  • Access to your Microsoft Azure portal (Entra ID)

  • Access to the OpenAthens admin interface as the domain administrator

Method

Create a connector

  1. Log in to the OpenAthens admin area as the domain administrator.

  2. Go to Management > Connections.

    Main Connections page. In the left sidebar are a list of federations to which the domain belongs and a list of local connections that are currently configured. There is also a button to create a new local authentication connection.The main content area shows key details such as your entity ID and scope.

  3. Under Local authentication in the left sidebar, press Create. A pop-up opens, showing available types of connector.

    Pop-up window titled 'Select local authentication system type'. Following are the options 'API', 'Evergreen ILS', 'Microsoft ADFS', 'OIDC', 'SirsiDynix', 'CAS', 'LDAP', 'Microsoft Azure' and 'SAML'. At the bottom of the window are 'Configure' and 'Cancel' buttons.

  1. Select Microsoft Azure and press Configure.

Pop-up window titled 'Add Azure authentication system'. Advisory text reads, 'Upload SAML 2 metadata via a URL or file'. There is a text input field labeled 'Metadata URL' and a file upload control. At the bottom of the window are 'Add' and 'Cancel' buttons.

  1. In Metadata URL, enter (for now) a dummy metadata URL: https://login.openathens.net/saml/2/metadata-idp/azure.openathens.net.

  2. Press Add. The connector is created with a temporary name. You can now view or edit its details.

    Details of a connector called 'Temporary Azure Relying Party'. The settings of the connector are divided into several tabs - 'Details' (the default), 'Relying party', 'Attributes', 'Permissions', 'Certificates', 'Advanced' and 'Contact'. Fields shown in the default Details tab include 'Display name', 'Description', 'Metadata URL', 'Entity ID' and 'SSO endpoint'. There are also buttons to 'Save changes' or to delete the connector.


  3. Go to the Relying party tab and copy the Metadata URL shown there. The URL looks something like https://login.openathens.net/saml/2/metadata-sp/yourdomain.com/la/1234.

    'Relying party' tab of the connector. It contains a single field, 'Metadata URL', in which a URL is pre-loaded.


  4. Paste the copied URL into your browser’s address bar. The URL will load an XML file. This is your SP metadata for the connection.

    Top part of an example XML metadata file.

  1. In the file, find the following pieces of information and save them in a convenient place:

    • Your entityID. This appears near the top of the file, as part of the XML element md:EntityDescriptor. It is identical to the relying party metadata URL that you copied earlier.

      Top part of the XML metadata file. It shows an XML element called 'EntityDescriptor', the first element in the file, which includes the attribute 'entityID'. The value of 'entityID' is highlighted.

    • Your AssertionConsumerService (ACS) location URL. This appears near the end of the file, in the element md:AssertionConsumerService. It will usually begin with “https://login.openathens.net/saml/2/acs”.

      Part of the metadata file, showing an XML element called 'AssertionConsumerService'. This element has an attribute called 'Location', the value of which is a URL. The 'Location' attribute is highlighted.

Add an application to Azure (Entra ID)

In Azure (Entra ID), perform the following steps:

  1. Create a new OpenAthens application.

  2. Set up SAML single sign-on for the application.

  3. Configure the SAML connection with the following settings:

    • Identifier: your entityID (delete any existing identifier)

    • Reply URL: your Assertion Consumer Service location URL (delete any existing URL).

  4. In the SAML certificates section, copy and save the URL of the federation metadata.

Consult Microsoft’s documentation for detailed instructions. Microsoft offers a tutorial on integrating with OpenAthens, Configure OpenAthens for single sign-on with Microsoft Entra ID.

Update the connection settings in OpenAthens

  1. In the OpenAthens admin area, go to Management > Connections and open your new Azure connector for editing.

  2. In the Details tab, replace Metadata URL with the metadata URL that you copied from Azure (Entra ID).

    Details tab of the connector 'Temporary Azure Relying Party. The 'Metadata URL' field is highlighted.

  3. Click the Refresh button following the Metadata URL. OpenAthens then pulls in the correct entityID, endpoints and certificates from Azure.

  4. Give the connector an appropriate Display name.

    manage-connections-azure-display-name-mapping.png

  5. Set Display name mapping to Use Subject NameID.

  6. Set Unique user mapping to Use Subject NameID.
    Later, you can specify attributes to use instead of Subject NameID, by filling in Display name attribute and Unique user attribute. Make these changes before going live. The identifiers that OpenAthens passes to resources are based on the unique user attribute, so the attribute that you use must be unique, persistent and non-reusable. (See the Microsoft documentation, Configure OpenAthens for single sign-on with Microsoft Entra ID.)

    Group of three checkboxes titled 'Status'. The options are 'Live', 'Visible' and 'Default'. The user can tick any, all or none of the boxes.

  7. Set the Status of the connector.

    1. If you have no existing OpenAthens users, you can tick the Live, Visible and Default statuses and start testing as soon as you have saved your changes.

    2. If you have existing OpenAthens users, leave Live, Visible and Default unticked. Otherwise, you may prevent existing users from logging in. You can still test, but will need to use debug mode.

  8. Press Save changes to finish.

You should now be able to test logging in and other functionality.

Set up any additional attributes

You may want to be able to do more with OpenAthens than simply sign the user in. For example, you can assign permissions based on the values of the attributes you send.

  1. In Azure (Entra ID), add any required attributes to the OpenAthens application that are not already available. See Microsoft Entra: Customize SAML token claims.

  2. In the OpenAthens admin area, configure the attributes. See Attribute mapping and Permission set rules.

OpenAthens caches attributes when a user signs in. Changes in Azure (Entra ID) will be picked up the next time the user starts an OpenAthens session.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close