Configuring Microsoft Entra ID as an OpenID Connect Provider in Keycloak

(TokenThis guide explains how to configure Microsoft Entra ID (formerly Azure AD) as an OpenID Connect v1.0 identity provider for Apporto NextGen through Keycloak. Use it as an end-to-end setup checklist to create the Keycloak OIDC broker, configure the Entra app registration, collect endpoint and credential values, map user attributes, and validate sign-in.

Overview

Keycloak acts as the identity broker for Apporto NextGen. Microsoft Entra ID authenticates users and sends OIDC tokens to Keycloak.

System

Purpose

Keycloak

Hosts the tenant realm and identity provider configuration.

Microsoft Entra ID

Hosts the app registration, client credentials, token claims, endpoints, and optional group or role assignments.

Before you begin

  • Confirm you have administrator access to the Keycloak realm for the customer tenant.

  • Confirm you have a Microsoft Entra administrator account that can create and manage app registrations.

  • Have a test Entra user available for validation.

  • Decide whether authorization will be driven by Entra app roles, group claims, or only by the user profile.

  • Keep both Keycloak and the Microsoft Entra administration consoles open during setup so you can copy values between them.

Configuration flow

  1. Add an OpenID Connect v1.0 identity provider in Keycloak and collect the Keycloak Redirect URI.

  2. Create an app registration in Microsoft Entra ID.

  3. Configure the Keycloak Redirect URI on the Entra app registration.

  4. Add ID token claims for username and email values.

  5. Collect endpoint values from Microsoft Entra ID.

  6. Configure the OIDC endpoints, client ID, and client secret in Keycloak.

  7. Optionally enable permissions and claims for group sync.

  8. Review advanced Keycloak settings.

  9. Create Keycloak mappers for username, email, and optional roles.

  10. Test sign-in end to end.


Instructions

Step 1: Add the OpenID Connect provider in Keycloak

  1. Sign in to the Keycloak administration console.

  2. Select the customer realm.

  3. Go to Identity Providers.

  4. If no providers exist, use the wizard. Otherwise, click Add provider.

  5. Select OpenID Connect v1.0.

    Screenshot 2026-08-24 at 4.13.51 PM.png

Set the provider alias

Enter a short, unique alias for the provider. Do not use spaces.

Example:

entraid-oidc

Do not use a discovery endpoint at this stage. You will provide endpoint values later.

Keep this Keycloak page open and copy the generated Redirect URI. You will need it when creating the Entra app registration.

Collect Keycloak service provider values

Copy the Redirect URI generated by Keycloak. The provider alias becomes part of the callback URI.

Example Redirect URI:

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

The provider alias becomes part of the Keycloak broker endpoint.

If the alias is entraid-oidc, Entra ID must redirect to /broker/entraid/endpoint exactly.


Step 2: Create the app registration in Entra ID

Create a new app registration in Microsoft Entra ID. This app authenticates users and redirects them to Apporto NextGen after successful sign-in.

  1. Sign in to Entra ID at https://entra.microsoft.com. If your Azure account has multiple Directories, make sure to Switch to the correct one before proceeding further.

  2. Go to App registrations → New registration.

  3. Name the app after the tenant realm, for example tenant-my-school-realm.

  4. Select Single tenant.

  5. Under Redirect URI, select Web.

  6. Paste the Redirect URI from Keycloak. Example: https://<your-keycloak-host>/realms/<your-realm>/broker/entraid/endpoint

  7. Click Register.

    register-app-tenant-my-school-20260707-234128.png

Step 3: Configure ID token claims

On the app registration (Token configuration), add the following claims of type ID:

  • email

  • family_name

  • given_name

  • upn

Screenshot 2026-09-02 at 7.22.34 PM.png

Ensure to also add Graphs as option during the above selection.

image-20261104-113924.png

These claims allow Keycloak to map the user’s username and email address reliably.


Step 4: Collect endpoint values from Entra ID

On the app registration Overview page, click Endpoints. Use these values to configure the Keycloak identity provider.

overview-my-school-redacted-20260707-234820.png

Step 5: Configure OIDC endpoints in Keycloak

You can configure the endpoints in either of the following ways.

Option A: Discovery

Keycloak field

Value

Use discovery endpoint

On

Discovery endpoint

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

Client authentication

Client secret sent as HTTP Basic authentication

Client ID

Application (Client) ID from the Entra ID OIDC application

Client Secret

Copy the secret Value from Certificates & secrets.

Client assertion signature algorithm

Algorithm not specified

Screenshot 2026-08-24 at 4.25.38 PM.png
Screenshot 2026-08-24 at 4.27.57 PM.png

Option B: Manual endpoint configuration

Use the Authority URL from Entra ID and build the Keycloak endpoint values as follows:

Authorization URL = <AUTHORITY_URL>/oauth2/v2.0/authorize
Token URL         = <AUTHORITY_URL>/oauth2/v2.0/token
User Info URL     = https://graph.microsoft.com/oidc/userinfo
Issuer            = <AUTHORITY_URL>/v2.0
JWKS URL          = <AUTHORITY_URL>/discovery/v2.0/keys

Do not populate the logout URL for Entra ID. Doing so signs the user out of Microsoft entirely, not just Keycloak, and may also sign them out of other applications using the same credentials.


Step 6: Complete the Keycloak configuration

  1. Back in Keycloak, enter the endpoint values from Step 5.

  2. Turn Validate Signature on.

keycloak-oidc-my-school-redacted-20260707-234529.png
  1. In Entra ID, go to Certificates & secrets → New client secret.

  2. For Client ID, copy the Application (client) ID from the app Overview. Do not use the secret ID.

  3. For Client Secret, copy the secret Value from Certificates & secrets.

  4. Enter the Client ID and Client Secret in Keycloak.

  5. Click Add.


Step 7: Review advanced Keycloak settings

After the Entra identity provider is added, review the advanced settings in Keycloak. Configure only the following fields unless your tenant requires something different.

  1. Enable send id_token_hint in logout requests.

  2. Turn on Disable User Info.

  3. Set Scopes to openid profile email.

    image-20260310-163552.png
  4. Turn on Trust Email.

  5. Set First login flow override to Apporto first broker login. This flow is provisioned with the realm.

  6. Click Save.


Step 8: Add identity provider mappers

Add the required mappers to ensure Keycloak receives and stores the correct username and email values.

Screenshot 2026-09-02 at 7.34.56 PM.png
  1. In Keycloak, go to Identity Providers → Your Entra ID Provider → Mappers.

  2. Click Add mapper.

  3. Create the recommended mappers listed below.

User field

Mapper type

Claim

Keycloak user attribute name

Username Mapper

Username mapper

${CLAIM.preferred_username}

Username

Email Attribute

Attribute Importer

upn

email

First Name Mapper

Attribute Importer

given_name

firstName

Last Name Mapper

Attribute Importer

family_name

lastName

Username mapper

Entra ID does not send the email in a form that Keycloak can reliably use as the username. Map the preferred username instead.

  • Mapper type: username mapper

  • Template: ${CLAIM.preferred_username}

    image-20260310-163957.png

Email mapper

Use an Attribute Importer because Entra sends the email value as upn.

  • Mapper type: Attribute Importer

  • Claim: upn

  • Attribute name: email

    image-20260310-164238.png


First Name Mapper

  • Map the given_name claim to the Keycloak firstName user attribute.

Screenshot 2026-09-02 at 7.33.35 PM.png

Last Name Mapper

  • Map the family_name claim to the Keycloak lastName user attribute.

Screenshot 2026-09-02 at 7.34.16 PM.png

Step 9: Optional group and role mapping in Entra ID

Complete this section only if Entra groups or app roles will be used for authorization.

Group mapping

If you plan to sync groups using the Apporto group mapper, grant Keycloak permission to read groups from Microsoft Graph.

  1. In Entra ID, go to API permissions → Add a permission.

  2. Choose Microsoft Graph → Application permissions → Group.Read.All.

    api-permissions-my-school-20260707-234257.png
  3. Click Grant admin consent.

    configured-permissions-my-school-20260707-234439.png
  4. Go to Token configuration → Add groups claim.

  5. Select Group ID for all group types.

  6. If the tenant has a very large number of groups, restrict the claim to groups assigned to the app. Otherwise, keep the default.

  7. Click Add.

    image-20260413-203219.png

Role mapping

If your environment uses direct role claims instead of groups, define App Roles on the app registration, then assign users or groups to those roles on the enterprise application. Entra emits the assigned roles in the roles claim automatically.

Supported role names are:

  • administrator

  • sub-admin

  • faculty

  • tech-support

msp and super-admin are Apporto-internal and cannot be assigned from an identity provider.


Step 10: Optional group and role mapping in Keycloak

Complete this section only if Entra sends groups or roles in the token.

Group mapping

If Entra sends group memberships, configure Keycloak to map the incoming group claim according to the tenant’s Apporto group mapping requirements.

Creating an Entra group alone is not enough. The group must be included in the token before Keycloak can map it.

Role mapping

You can map a role from Entra ID to a role in your Apporto NextGen tenant. NextGen recognizes these role names: administrator, sub-admin, faculty, and tech-support.

Prerequisite: role mapping takes effect only when Allow SSO to override locally-assigned roles is enabled on Setup → Identity Management in Apporto. While it is off by default, NextGen keeps each user’s locally assigned role and ignores roles sent by Entra ID.

Manage each user’s role in one place, either Entra ID or NextGen, not both. When Entra sends a role it is used. If it does not send one for a user, the role assigned manually in NextGen applies.

  1. Confirm the target role exists as a client role on your tenant’s OIDC client in Clients → your tenant client → Roles, named exactly one of the role names above.

  2. In Entra ID, define App Roles on the app registration, then assign users or groups to them on the enterprise application. Entra emits the assigned roles in the roles claim automatically.

  3. On the Entra identity provider in Keycloak, go to Mappers → Add mapper and choose Claim to Role.

Setting

Value

Claim

roles

Claim Value

The Entra app-role value that should grant it, for example Faculty

Role

The client role on your tenant client, for example faculty

Sync Mode Override

Force

Use Advanced Claim to Role for multiple values or pattern matching.

Do not enable Lightweight Access Tokens on the tenant client. The role is delivered under resource_access.{client}.roles, which lightweight tokens strip.

For the full role model, including SAML providers, LDAP/AD group-to-role assignment, and group syncing, see Single Sign-On (SSO) with Keycloak.


Step 11: Test the configuration

  1. Open the Apporto NextGen sign-in flow for the configured tenant.

  2. Choose the Microsoft Entra identity provider option if prompted.

  3. Sign in with a user allowed to access the Entra application.

  4. Confirm Entra redirects the browser back to the Keycloak broker endpoint successfully.

  5. Confirm the user profile includes the expected username and email address.

  6. If groups or roles are configured, confirm the expected Keycloak or Apporto role is applied.


Troubleshooting

Issue

What to check

Page not found or invalid redirect

The Entra Redirect URI must exactly match the Keycloak Redirect URI, including the broker alias.

Invalid issuer or endpoint error

Confirm the v2.0 endpoints and issuer are used consistently.

Invalid signature

Confirm Validate Signature is enabled and Keycloak can access the current Entra signing keys.

Missing email address

The Entra token must include the expected upn or email claim, and the Keycloak email mapper must use the same claim name.

User cannot access the application

Confirm the user is allowed to access the Entra enterprise application and the app registration is configured for the correct tenant.

Group is not in the token

Entra group membership alone may not emit a group claim. Configure the groups claim in the app registration token configuration.

Group or role mapping does not work

The token claim name and value in Keycloak must exactly match the values sent by Entra ID.

Role not applied in Apporto

Confirm Allow SSO to override locally-assigned roles is enabled if roles should be managed by Entra ID.


Final checklist

  • OpenID Connect v1.0 identity provider created in Keycloak
  • Provider alias added without spaces
  • Keycloak Redirect URI copied to the Entra app registration
  • Entra app registration created as a single-tenant Web application
  • ID token claims configured for UPN and email
  • Endpoint values collected from Entra ID
  • OIDC endpoints configured in Keycloak
  • Client ID and client secret added to Keycloak
  • Optional group claims configured if group mapping is required
  • Advanced Keycloak settings reviewed and saved
  • Username and email mappers created in Keycloak
  • Optional group or role mappers created, if required
  • Sign-in tested successfully

The Microsoft Entra OpenID Connect identity provider is configured when users can sign in to Apporto NextGen through Entra ID and receive the expected profile and authorization values.