Configuring Microsoft Azure as an authentication provider for OpenAthens

This section assumes a basic level of familiarity with the Azure interface (Entra ID). Whilst our service desk will always try to be helpful, they can only support the OpenAthens end of the connection.

Preparation

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 > Add and select the Azure connector
   
   
3. Enter the dummy metadata URL: https://login.openathens.net/saml/2/metadata-idp/azure.openathens.net
   
   
4. Save
   
   

5. Go to the </> relying party tab and copy the URL displayed there - it will look similar to:

   
   https://login.openathens.net/saml/2/metadata-sp/yourdomain.com/la/1234
   
   
6. Paste the URL into your address bar. This is your SP metadata for the connection.
   
   
7. Find your entityID within the metadata and save it somewhere -  it will be near the top of the page and be identical to the relying party URL
   
   

8. Identify your AssertionConsumerService (ACS) location URL within the metadata and save it somewhere - it will be near the bottom of the page and look similar to:

   
   https://login.openathens.net/saml/2/acs/yourdomain.com/la/1234
   
   

Add an application to Azure (Entra ID)

1. Go to Active Directory > Enterprise applications > All applications, click the new application button, search for and select OpenAthens, and click create
   
   
2. Go straight to part 2, set up single sign-on
   
   
3. Choose SAML
   
   
4. You should now be on the SAML single sign-on configuration page
   
   
5. Open the basic SAML configuration settings by clicking on the edit button
   
   
6. Add the entityID from earlier as a new identifier and delete the old one
   
   
7. Add the ACS location URL from earlier as a new reply URL and delete the old one
   
   
8. Back on the SAML single sign-on configuration page, go to the SAML certificates section and copy the app federation metadata URL
   
   
9. Save

Update the settings in OpenAthens

1. Go to your new connector in the admin area
   
   
2. Delete the metadata URL and replace it with the one you just copied from the configuration page in Azure, then click the save button
   
   
3. Click the refresh button next to the metadata URL to pull in the correct entityID, endpoints, and certificates from Azure
   
   
4. Rename the connector to something meaningful for your users
   
   
5. Set the display name and unique user mapping to use Subject NameID by using the radio button. You can specify attributes to use instead at a later point, as long as you make the change before you go 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.
    
6. Finally, set the status and save
   
   
   1. If you have no existing OpenAthens users, you can select live, visible and default under status and start testing as soon as you have saved
      
      
   2. If you have existing OpenAthens users, leave those three checkboxes cleared when you save, or you may stop existing users from being able to sign in. You can still test, but you will need to use debug mode - see: How to use debug mode
      
      

You should now be able to test that signing in works and add any additional bits you need. 

Set up any additional attributes you need to send to OpenAthens

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.

In Azure (Entra ID)

1. In the OpenAthens application you set up in the Azure portal, go to the user attributes section and see if the attribute you want to send us is already available.
   
   1. If it is, copy the name for later, then move on to the OpenAthens step. The attribute name is case sensitive, and in Azure it will usually start with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/...
   2. If the attribute is not already there, select the view and edit all other user attributes checkbox where you can add it - see: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-saml-claims-customization

In OpenAthens

1. See: Attribute mapping
2. See: Permission set rules

OpenAthens will cache these attributes when the user signs in, so changes in Azure (Entra ID) won't be picked up until the next time the user starts an OpenAthens session.