This guide goes through the steps of configuring Azure AD OAuth for Elements. This configuration allows Elements to use Azure AD to log users in. It is suggested to use Azure AD OAuth together with Azure AD User store.

Setting up an Azure App Registration

The first step to enable Azure AD integration is to create an App Registration inside the Azure AD tenant. Elements will access Azure on behalf of this App.

Elements will need 3 pieces of configuration to connect using this app. These are: Client ID, Tenant ID and Client Secret.

NOTE: If you are also setting up an Azure AD User store, it is enough to set up a single App registration and configure it for both purposes. Steps 1-5 are the same for both of these setups.

The steps to create the app:

1. Navigate to the Azure Portal. Search for 'App Registrations' and go to the service

2. Click New registration

3. Provide an application name, such as Elements integration. You can leave the Supported account types and Redirect URI unchanged. Click Register. 

4. After the app is created, note down the Application (client) ID and the Directory (tenant) ID from the Overview page.

5. Next step is to generate the Client Secret (the last remaining piece of configuration required by Elements). Navigate to the Certificates & Secrets page, select the Client secrets tab and create a new client secret. The Description of the secret is optional, and the expiration is up to you. Elements will always need a valid secret, which has to be re-generated after the old one expires. Note down the secret value, which will be used as the Client Secret and it will be provided to Elements.

6. Go to the Authentication page. Click Add a platform and select Web.

7. Enter the Redirect URI of the application, which is https://[your-elements-hostname]/api/account/oauth/callback/microsoft. Also make sure that you check both the Access tokens and ID tokens checkboxes for Implicit grant and hybrid flows. You can leave Front-channel logout URL blank.

The final configuration should look like this:

8. Lastly, the appropriate permissions need to be set for the app. This will allow Elements to query the required resources (users & groups) from Azure AD. Navigate to the API permissions page.

9. Click Add a permission. On the side panel that pops up, select Microsoft Graph. 

10. Select Delegated permissions, then select the email, openid and profile permissions, then click Add permissions. The page should look like this:

Configuring Elements to use the Azure AD OAuth

To configure Elements, open the appsettings.json, then:

1. Navigate to the LoginSettings section

2. Set the AuthType to OAuth

3. Navigate to the OAuthSettings section

4. Set the OAuthType to Microsoft

5. Navigate to the Microsoft section

6. Fill out the Microsoft section with the TenantID, ClientID and ClientSecret of the Azure application.