Configure the authentication in Azure

This page explains how to configure the authentication for a Semarchy xDM instance deployed on Azure, including authentication to Microsoft Entra ID.

Microsoft Entra ID (ME-ID) is the name of the identity and access management service formerly known as Azure Active Directory (AAD). To learn more about this name change, see the documentation on the Microsoft website.

Default authentication configuration

Semarchy xDM is configured by default to use the built-in authentication. A first administrator user is created with the admin account and password that you have configured during the deployment.

Connect with this user to create new users, configure identity management, or to configure Microsoft Entra ID authentication as explained below.

Configure Microsoft Entra ID

Register the application in ME-ID

  1. In the Azure portal, select Microsoft Entra ID.
    Opening Microsoft Entra ID

  2. Under the Manage section in the navigation pane, select App registrations, and then click New registration.
    New registration

  3. In the Register an application page, enter the following information:

    • Name: type a name for the registered application (e.g., the name of your instance).

    • Supported account types: select who can use this application.

    • Redirect URI: leave this section empty.

You will set the Redirect URI parameters once you have configured the identity provider in Semarchy.

App registration

  1. Click Register. The application registration is created and opens.
    App created

  2. Under the Manage section in the navigation pane, select Certificates & secrets, and then click New client secret.
    Certificates and secrets

  3. In the Add a client secret side sheet that appears, describe the client secret in the Description field, and then click Add.
    Add client secret

  4. The secret is created. Note the client secret in the Value column, as you will need it later in the configuration.
    ME-ID secret value

  5. Under the Manage section in the navigation pane, select API permissions, and then click Add a permission.

  6. In the Request API permissions side sheet that appears, select Microsoft Graph.
    Configuring API permissions

  7. Select Delegated permissions and then enter directory in the Select permissions search field to filter the permissions.

  8. Expand the Directory section and select the Directory.Read.All permission, then click the Add permissions button.
    Selecting API permissions

  9. Click the Grant admin consent for…​ button and then click OK to confirm.
    Granting consent

  10. Under the Manage section in the navigation pane, select Manifest.

  11. In the editor, search for the groupMembershipClaims property, currently set to null. Change its value to SecurityGroup.
    Configuring group membership claims

You may need to adjust the HTTP request header size, as this setting can cause the token’s claims to include a large number of groups, which may lead to a Request header is too large error. To resolve this, set the TOMCAT_HTTP_MAX_HEADER_SIZE environment variable to a higher value in the startup configuration.

  1. Click Save.

  2. In the navigation pane, select Overview. In the Essentials section, note the Application (client) ID value, as it will be used as the client ID later in the configuration.
    Viewing the client ID

  3. Select the Endpoints button. From the side sheet that appears, copy the URL of the OpenID Connect metadata document. This value will be used as the Issuer URL later in the configuration.

You should only copy the part of the URL until 2.0, as shown below.

Open ID Connect Metadata Document

At that stage, you should have the three following values:

  • Client ID: the Application (client) ID on the App registration Overview page.

  • Client Secret: the value of the secret created on the App registration Certificate and secrets page.

  • Issuer URL: the OpenID Connect metadata document copied from the App registration Endpoints side sheet.

Identify ME-ID groups to use in Semarchy

Semarchy xDM uses roles that need to be mapped on groups in Microsoft Entra ID. You must identify the user groups and their corresponding roles in Semarchy.

  1. In the Azure portal, select Microsoft Entra ID.
    Opening Microsoft Entra ID

  2. Under the Manage section in the navigation pane, select Groups. Identify the groups that you want to map on specific roles and note their Object Id value.
    Selecting groups

Configure Semarchy xDM to use ME-ID

  1. Access the Semarchy xDM Welcome page, open Configuration, and then select Identity Management.

  2. Click the Plus sign in blue circle Add provider button.

  3. In the Provider type field, select OpenID Connect.

  4. In the Name field, enter an identity provider name and save your changes when prompted to do so.

  5. In the identity provider editor, enter the following values:

  6. Note the value of the Redirect URL property, which you will declare in Microsoft Entra ID. This value is designated below as redirect URL.

  7. Click the Floppy disk Save button.

  8. Select the Roles Mapping tab.

  9. For each group that you identified in Microsoft Entra ID, click the Add Role Mapping button and enter the following details for the mapping:

    • Provider role: name of the role in Microsoft Entra ID.

    • Mapped role: corresponding role(s) in your Semarchy instance.

Table 1. Examples of a role mapping
Provider role Mapped roles

0450dc43-46d7-40d3-95d4-779a723f347a

semarchyConnect,semarchyAdmin

9b231924-22d4-4bae-8a1c-1860c5e1d387

semarchyConnect,dataSteward

7f9d3722-cee2-48a3-95e2-c6be68ab3113

semarchyConnect,businessUser

  1. Save the identity provider.

Declare a platform for Semarchy xDM in ME-ID

You must now enter in Microsoft Entra ID the redirect URI of the identity provider you have defined in Semarchy.

  1. In the Azure portal, select Microsoft Entra ID.

  2. Under the Manage section of the navigation pane, select App registrations, and then select the application you previously registered.

  3. Under the Manage section of the navigation pane, select Authentication.

  4. Select the Add a platform button, and then select Web.
    Adding a platform

  5. Under Redirect URIs, enter the redirect URL from the identity provider’s configuration in Semarchy.

  6. Leave the Front-channel logout URL field empty.

  7. Select the Access Tokens and ID Tokens checkboxes in the Implicit grant and hybrid flows section.
    Platform properties

  8. Click Configure to apply your changes.

Test and activate the identity provider in Semarchy

  1. Click the Test button and follow the instructions to test the configuration of the identity provider.

  2. If the test is successful, click the appropriate identity provider toggle in the list to activate it.