Integrating Microsoft Entra ID with Keycloak for MTG CLM Authentication

× Magnified Image

This guide walks you through configuring Microsoft Entra ID (formerly Azure AD) as an identity provider for Keycloak, enabling single sign-on for MTG CLM users.

Prerequisites: Microsoft Entra ID administrative privileges, Keycloak administrative access, and MTG CLM environment access.

Creating the App Registration in Entra ID

To allow Keycloak and MTG CLM to authenticate users against your Microsoft environment, you must first register an application in your Entra ID tenant.

  1. Log in to Azure Portal 🔗.

  2. Click the hamburger button on the top left corner.

    entra0

  3. Select Microsoft Entra ID.

    entra0a

  4. Click + Add and then App Registration.

    entra0b

  5. Enter a descriptive Name for the application (e.g., MTG CLM - Keycloak).

  6. Under Supported account types, select Single tenant only.

  7. Leave the Redirect URI blank for now. You will configure this later when setting up Keycloak.

  8. Click Register.

    entrab0

Once the application is created, you are taken to the Overview page.

Copy and securely store the following two values, as you will need them for the Keycloak configuration:

  • Application (client) ID

  • Directory (tenant) ID

    entra0c

To allow MTG CLM to read user and directory objects within your tenant, you must grant the App Registration specific Microsoft Graph API permissions.

  1. In your App Registration menu, select API permissions from the left sidebar.

    entra0d

  2. Click + Add a permission.

    entra0e

  3. Select Microsoft Graph.

    entra0f

  4. Select Application permissions (not Delegated permissions).

    entra0g

  5. In the search bar, locate and check the following permission: Directory.Read.All. Click Add permissions at the bottom of the screen.

    entra0h

  6. Once the permissions are added, select them and click the Grant admin consent for [Your Tenant Name] button located above the permissions list.

    entra0i

  7. Click Yes in the confirmation prompt. You should be seeing a similar screen to:

    entra0igranted
If the Grant admin consent button is greyed out, your current account does not have the Global Administrator or Privileged Role Administrator rights required to authorize these permissions.

Generating the Client Secret

Keycloak requires a client secret to authenticate against your Entra ID tenant securely.

  1. In your App Registration menu, select Certificates & secrets from the left sidebar.

    entra00a

  2. Click + New client secret.

  3. Enter a descriptive Description (e.g., MTG CLM-Secret) and select an Expires duration according to your security policy.

  4. Click Add.

    entra00b
Copy the Value string immediately and store it in a secure location. This value will be permanently hidden once you leave this page, and you cannot retrieve it later. You will paste this value into Keycloak in the next section.

Configuring Keycloak Identity Provider

Accessing Identity Provider Configuration

  1. Sign in to your Keycloak administration console.

  2. Navigate to your target realm for MTG CLM integration.

  3. Select Identity Providers from the left navigation menu.

  4. Click OpenID Connect v1.0.

    entra1

Configuring Provider Settings

1. Basic Configuration

  • Alias: Enter "microsoft-entra-id" (or organizational standard).

  • Display Name: Enter "Microsoft Entra ID".

    Make sure you store your Redirect URI now. You are going to need it later.
    entra2

2. OpenID Connect Settings

The metadata fields related to endpoints will be automatically populated upon pasting.

  • Client Authentication: Select "Client secret sent in the request body" from the dropdown list.

  • Client ID: Retrieve from portal.azure.com → Overview.

  • Client Secret: Retrieve from Generating the Client Secret.

Make sure to timely renew the client secret before your selected expiration date.

Paste the Client Secret Value to the appropriate field in Keycloak and keep Client assertion signature algorithm to "Algorithm not specified".

  • The completed page should now look like this:

    entra6

  • Click "Add" to proceed.

  • Now copy your redirect URI you saved above and paste it in portal.azure.com

    entra7

  • Click "Add a platform" and then select "Web".

    entra8

  • Paste the Redirect URI in the appropriate field and then select "Configure" to finish.

  • In Keycloak go to Clients (within MTG ERS realm) and choose the account-console client.

  • In Access Settings make sure Web origins is set to "*".

    entra9

Testing Authentication Flow

Validating Configuration

Testing MTG CLM Access

  • Navigate to MTG CLM login page.

    entra10

  • Click SSO/Keycloak authentication option.

  • The redirect chain is as follows: MTG CLM → Keycloak → Microsoft → back to MTG CLM.

    entra11

  • Confirm authentication and successful profile creation both in Keycloak and in MTG CLM.

    entra12
    entra13

Configuring Keycloak Roles for Entra ID Federation

This section extends the Entra ID authentication configured earlier by mapping Entra ID app roles to Keycloak realm roles.

Use the same Entra ID app registration and Keycloak identity provider configured in the previous sections.

The identity provider and its redirect URI are already configured. You do not need to create another identity provider or register the same redirect URI again.

Prerequisites

  1. Complete the authentication setup in the previous sections and verify that you can sign in using Entra ID.

  2. Ensure you have access to the Azure Portal with permissions to manage app roles and assignments.

  3. Ensure you have administrative access to the same Keycloak realm used for authentication.

  4. Have an Entra ID test user available.

Defining App Roles in Entra ID

Create the app roles that you want to map to Keycloak realm roles. Use the Entra ID app registration configured in the first part of this guide.

  1. Navigate to Microsoft Entra ID → App registrations and select your app.

  2. Go to App roles → Create app role.

  3. Fill in the following fields:

    Field Example Value Notes

    Display name

    CLM Admin

    Human-readable label

    Value

    clm_admin

    Value that Keycloak will match in the roles claim

    Description

    Full administrative access to CLM

    Description of the intended role

    Allowed member types

    Users/Groups

    Allows assignment to users and groups

  4. Click Apply.

  5. Repeat to create additional roles as needed, such as clm_viewer.

    entraid createapprole1
The Value field must exactly match the Claim value configured in the Keycloak mapper. This guide uses lowercase values with underscores as a naming convention. Use clm_admin consistently when following this example.
Creating an Entra ID app role does not itself grant permissions in MTG CLM. The mapped Keycloak role must provide the intended access in your application configuration.

The following screenshot provides an additional example of app roles. When following this guide, use clm_admin consistently (disregard the clm-admin value shown in the screenshot below).

keycloak extra1

Assigning the App Role to Your Test User

  1. Go to Enterprise applications and select the application associated with the app registration used above.

  2. Select Users and groups → Add user/group.

  3. Under Users, search for and select your test user.

  4. Under Select a role, choose the role you created, such as CLM Admin.

  5. Click Assign.

Verify that your test user appears in the Users and groups list with the assigned role.

Accessing the Configured Entra ID Identity Provider

Use the existing OpenID Connect identity provider to configure role mapping.

  1. Sign in to the Keycloak administration console.

  2. Select the same realm used in the authentication setup.

  3. Go to Identity Providers.

  4. Open the provider with the alias microsoft-entra-id, or the alias you chose during setup.

  5. Confirm that its Client ID matches the Application (client) ID of the Entra ID app registration where you defined and assigned the app roles.

Keep the existing provider settings and redirect URI. The role mappers configured below will use this connection.

The following screenshot shows where the redirect URI was registered in Entra ID during the initial setup. It is included for reference; you do not need to repeat the registration.

entraid redirect uri

Preparing the Keycloak Realm Role

The target Keycloak realm role must exist before you configure the mapper.

  1. In the same Keycloak realm, go to Realm roles.

  2. Locate the role that provides the intended access in MTG CLM.

  3. If your application configuration requires a new role, create it before proceeding.

The mapper example below uses the Keycloak realm role clm_admin. If your environment uses a different role name, select that role instead.

The Entra ID app role value and the Keycloak realm role name do not have to be identical. The mapper explicitly connects them. In this example, both are clm_admin.

Adding Mappers in Keycloak

  1. Go to Identity Providers and open the Entra ID provider configured earlier.

  2. Open the Mappers tab.

  3. Click Add mapper.

    keycloak add mapper

  4. Configure the mapper:

    Field Value

    Name

    Admins

    Mapper type

    Claim to Role

    Claim

    roles

    Claim value

    clm_admin

    Role

    Select the Keycloak realm role clm_admin, or the appropriate existing role for your environment

    Sync mode override

    Force

  5. Save the mapper.

    keycloak extra3

  6. Repeat for any additional app roles that you want to map.

This mapper assigns the selected Keycloak realm role when the Entra ID token contains clm_admin in its roles claim.
Match the Claim value to the Entra ID app role Value exactly. If a screenshot shows a different example value, use the values defined in your own configuration.

The mapper does not create or assign app roles in Entra ID. Define those roles and assign them to the appropriate users or groups in Entra ID before testing.

Verifying Federation and Role Assignment

Test the existing connection and the new mapper together by completing a fresh federated sign-in.

  1. Log out of the test user’s Keycloak session.

  2. Open a new private or incognito browser session.

  3. Navigate to the account console for the realm used throughout this guide:

    https://<keycloak-host>/realms/<realm-name>/account

  4. Select the sign-in option for your Entra ID provider. Its display name was configured as Microsoft Entra ID, unless you chose another name.

  5. Sign in with the Entra ID test user to whom you assigned the app role.

  6. Confirm that you reach the Keycloak account console.

  7. In your regular browser window, open the Keycloak administration console.

  8. Go to Users and select the test user.

  9. Open Role mapping and confirm that the role selected in the mapper, such as clm_admin, is assigned.

  10. Sign in to MTG CLM as the test user and verify that the user has the intended application access.

Confirming a role assignment in Keycloak verifies the mapper’s result. Checking access in MTG CLM also verifies that the application uses the assigned role as intended.

Troubleshooting Redirect Connectivity

If the browser times out after Microsoft sign-in, check whether it can reach the Keycloak callback address.

  • Open <keycloak-host>; in the same browser.

  • If Keycloak is available only on an internal network, connect to the required network or VPN.

  • Confirm that the redirect URI registered in Entra ID exactly matches the URI displayed by the existing Keycloak identity provider.

Keycloak does not have to be publicly accessible if the user’s browser can reach it through the required network.

A localhost redirect can work when the browser and Keycloak run on the same machine and the redirect URI is registered correctly. If the browser runs on another machine, localhost refers to that machine instead of the Keycloak server.

If live federation cannot be tested, the manual check below can verify direct role assignment separately.

Manual Role Assignment Check (If Live Federation Is Unavailable)

Use this check only to test direct Keycloak role assignment and, where local sign-in is available, the application’s handling of that role.

This check does not verify Entra ID authentication, the roles claim or the identity provider mapper. Complete the federated sign-in test when the connection becomes available.

  1. In the Keycloak administration console, select the same realm used throughout this guide.

  2. Go to Users and select a dedicated local test user, or create one using Add user.

  3. Open the user’s Role mapping tab.

  4. Assign the target realm role, such as clm_admin.

  5. Confirm that the role appears in the user’s role assignments.

  6. If local authentication is enabled and the test user has the required credentials, sign in to MTG CLM with that user and check the resulting access.

Use a separate local test user so that a manually assigned role cannot be mistaken for a role assigned by the Entra ID mapper.

Troubleshooting

Issue Checks

No Entra ID sign-in option on the Keycloak login page

  • Confirm that the existing identity provider is enabled.

  • Verify that you are accessing the correct realm.

  • Check the provider’s display name. The option may be labelled Microsoft Entra ID rather than Sign in with Microsoft.

  • Check whether the provider is configured to be hidden from the login page.

Redirect URI mismatch

  • Copy the redirect URI displayed by the existing Keycloak identity provider.

  • Compare it with the URI registered under Authentication in the Entra ID app registration.

  • Check the hostname, realm and provider alias. The URI must match exactly.

  • Update the existing Web platform configuration if a correction is needed.

Browser times out after Microsoft sign-in

  • Confirm that the browser can reach the Keycloak hostname.

  • Connect to the required network or VPN.

  • Check whether the callback uses a hostname or port that is inaccessible from the browser.

  • Do not enable implicit grant options as a general fix for a connectivity timeout.

Sign-in succeeds but the expected Keycloak role is missing

  • Confirm that the app role is assigned to the test user in the correct Entra ID enterprise application.

  • Confirm that the provider’s Client ID identifies that same app registration.

  • Check that the mapper’s Claim is roles.

  • Match the mapper’s Claim value exactly to the Entra ID app role Value.

  • Confirm that the mapper selects the intended existing Keycloak realm role.

  • Complete a fresh federated sign-in after saving changes.

Role information appears under user attributes but no realm role is assigned

  • Check that you configured a Claim to Role mapper.

  • An attribute mapper alone does not assign a Keycloak realm role.

  • Verify the target role selected in the role mapper.

A mapper for another role does not assign that role

  • Define the corresponding app role in Entra ID.

  • Assign it to the test user or an applicable group.

  • Verify that the mapper matches that app role’s exact value.

  • Repeat the federated sign-in test.

An existing Keycloak account conflicts with the first federated sign-in

  • Follow the configured account-linking flow to verify ownership of the existing account.

  • If the expected linking option is unavailable, review the realm’s first broker login flow with your Keycloak administrator.

A changed Entra ID role assignment is not reflected in Keycloak

  • Confirm that the relevant mapper uses Sync mode override set to Force.

  • Log out and start a new federated sign-in.

  • Verify the current assignment in the correct Entra ID enterprise application.

  • Check whether the Keycloak role was also assigned manually or inherited through another role or group.

Multiple Entra ID identity providers exist in the realm

  • Identify the provider configured in the first part of this guide.

  • Confirm that the test user signs in through that provider.

  • Ensure the role mapper is attached to that same provider.

  • Review unused providers before disabling them. Multiple providers are not inherently invalid.

The role is assigned in Keycloak but application access is incorrect

  • Confirm that MTG CLM is configured to use the selected Keycloak role.

  • Verify that the application’s token contains the role information it expects.

  • Check the application’s role-to-permission configuration.