Microsoft Entra ID via Keycloak

Overview

This guide describes how to configure Microsoft Entra ID (formerly Azure Active Directory) as an SSO identity provider in Keycloak for your SUSE Cloud Observability tenant.

The authentication flow is:

User -> Keycloak (identity broker) -> Microsoft Entra ID

Keycloak delegates authentication to Entra ID and maps Entra ID groups to Keycloak roles. SUSE Cloud Observability then receives those roles from Keycloak through its standard integration.

Prerequisites

  • A SUSE Cloud Observability tenant with Advanced Keycloak management mode enabled — see User Management.

  • An Azure tenant with administrative access to register applications in Entra ID.

  • The Keycloak realm name and base URL (for example, https://keycloak.acme.com and realm acme).

Step 1: Register an application in Entra ID

  1. Sign in to the Azure portal and navigate to Microsoft Entra ID > App registrations > New registration.

  2. Set a display name, for example Keycloak SSO.

  3. Under Redirect URI, select Web and enter the Keycloak broker endpoint URL. You can find this URL in the Keycloak Admin Console by navigating to Identity Providers > Add provider > OpenID Connect v1.0 — the Redirect URI is shown at the top of the configuration page. It follows the pattern:

    https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint

    Replace <alias> with the identity provider alias you will configure in Keycloak (for example, entra-id).

  4. Click Register.

  5. On the app overview page, note the Application (client) ID and the Directory (tenant) ID.

  6. Navigate to Certificates & secrets > Client secrets > New client secret. Add a description, select an expiry period, and click Add. Copy the secret Value immediately — it won’t be shown again.

  7. To include group memberships in the token, navigate to Token configuration > Add groups claim. Select the group types you want to expose. This guide assumes you use Group ID.

For more details, see the Microsoft documentation on registering an application.

Step 2: Configure the identity provider in Keycloak

  1. Sign in to the Keycloak Admin Console and select your realm.

  2. Navigate to Identity Providers > Add provider > OpenID Connect v1.0.

  3. Configure the following settings:

    Setting Value

    Alias

    An identifier for this provider, for example entra-id. This value is used in the redirect URI.

    Display Name

    The name shown on the Keycloak login page, for example Microsoft Entra ID.

    Discovery endpoint

    https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

    Client ID

    The Application (client) ID from Step 1.

    Client Secret

    The client secret value from Step 1.

    Client Authentication

    Client secret sent as post

    Default Scopes

    openid email profile

  4. Click Save.

  5. Verify the provider appears on the Keycloak login page by opening your realm’s login URL in a browser.

For more details, see the Keycloak documentation on OpenID Connect v1.0 identity providers.

Step 3: Configure mappers

Mappers transform claims from Entra ID into Keycloak user attributes or roles.

Username mapper

By default, Keycloak uses the identity provider’s subject ID as the username. To use the email address instead:

  1. In the Keycloak Admin Console, navigate to Identity Providers > entra-id > Mappers > Add mapper.

  2. Set Mapper type to Username Template Importer.

  3. Set Template to $\{CLAIM.email}.

  4. Click Save.

Group-to-role mapper

To map Entra ID group memberships to Keycloak roles:

  1. Navigate to Identity Providers > entra-id > Mappers > Add mapper.

  2. Set Mapper type to Claim to Role.

  3. Set Claim to groups.

  4. Set Claim Value to the Entra ID group Object ID (for example, aaaaaaaa-bbbb-1111-2222-aabbccddeeff).

  5. Under Role, select the Keycloak role to assign.

  6. Click Save.

Repeat this for each Entra ID group that should be mapped to a Keycloak role.

You can find Entra ID group Object IDs in the Azure portal under Microsoft Entra ID > Groups. The Object ID is shown in the second column.

Step 4: Verify the role mapping chain

The complete mapping chain is:

Entra ID group -> Keycloak role -> SUSE Cloud Observability role

  1. Entra ID groups to Keycloak roles — Configured in Step 3 using claim-to-role mappers.

  2. Keycloak roles to SUSE Cloud Observability roles — Roles map through the predefined Keycloak groups (stackstate-k8s-troubleshooter, stackstate-k8s-admin). No additional SUSE Cloud Observability configuration is needed — the platform automatically maps Keycloak roles associated with these groups to the corresponding SUSE Cloud Observability roles.

To verify the full chain:

  1. Log in to SUSE Cloud Observability using a test user who is a member of an Entra ID group.

  2. Confirm that the user is assigned the expected SUSE Cloud Observability role.

  3. If the user doesn’t have the correct role, check the Keycloak user’s role assignments and group memberships.

See also