KeycloakPro

Introduction

Configuring Microsoft Entra ID as an identity provider in Keycloak lets users sign in with their Microsoft work or school account (or personal Microsoft account, depending on your app registration). Keycloak has a built-in Microsoft provider type that pre-fills the correct OAuth 2.0 endpoints.

This guide covers both single-tenant setups (your Entra ID tenant only) and multi-tenant setups (any Microsoft account or any organizational account). Keycloak 24+ and a Microsoft Entra ID (formerly Azure Active Directory) tenant are required.

How identity brokering works

The login flow goes: user clicks "Sign in with Microsoft" → Keycloak redirects to Entra ID → user authenticates → Entra ID sends an authorization code to Keycloak's broker endpoint → Keycloak exchanges it for tokens → Keycloak creates or links the user → user lands in your application.

The redirect URI you register in Azure is:

https://keycloak.example.com/realms/YOUR_REALM/broker/Microsoft/endpoint

The alias Microsoft is the default for the built-in Microsoft provider. If you use the generic OIDC provider instead, the alias is whatever you choose.

Prerequisites

  • Keycloak 24+ running on HTTPS
  • A Keycloak realm with admin access
  • An Azure account with permission to create app registrations in a Microsoft Entra ID tenant

Step 1 — Register an application in Azure Portal

Go to the Azure Portal at portal.azure.com:

  1. Microsoft Entra ID → App registrations → New registration
  2. Name: keycloakPro
  3. Supported account types — choose based on your use case:
    • Accounts in this organizational directory only — single tenant, your users only
    • Accounts in any organizational directory — multi-tenant, users from any Microsoft organization
    • Accounts in any organizational directory and personal Microsoft accounts — broadest access
  4. Redirect URI: Web → https://keycloak.example.com/realms/YOUR_REALM/broker/Microsoft/endpoint
  5. Click Register
The account type determines which users can authenticate — single tenant is the right choice for internal employee login

After registration, note the Application (client) ID and Directory (tenant) ID on the app's Overview page. You'll need both.

Copy both IDs now — the client ID goes into Keycloak, and the tenant ID identifies your specific Entra ID directory for single-tenant setups

Step 2 — Create a client secret

  1. Certificates & secrets → New client secret
  2. Description: keycloakPro
  3. Expires: choose 12 or 24 months (calendar this for rotation)
  4. Click Add
  5. Copy the Value immediately — Azure hides it after you leave the page
Copy the Value column, not the Secret ID — the Value is the actual secret string you paste into Keycloak

Step 3 — Configure the Identity Provider in Keycloak

In the Keycloak admin console:

  1. Select your realm
  2. Identity Providers → Add provider → Microsoft
  3. Client ID: paste the Application (client) ID from Step 1
  4. Client Secret: paste the client secret Value from Step 2
  5. Default Scopes: openid profile email (Keycloak pre-fills this)

Click Add.

The built-in Microsoft provider uses the common tenant endpoint by default — it accepts any Microsoft account type based on your app registration's account type setting

3.1 — Single-tenant restriction (optional)

If you registered a single-tenant app, the built-in Microsoft provider still uses the common endpoint by default. Any user with a valid Microsoft account can attempt login, but Entra ID will reject users outside your tenant during the token exchange.

For a stricter setup using only your tenant's endpoint, use the generic OpenID Connect v1.0 provider instead:

  1. Identity Providers → Add provider → OpenID Connect v1.0
  2. Alias: microsoft
  3. Client ID: Application (client) ID
  4. Client Secret: client secret Value
  5. Default Scopes: openid profile email

This approach locks authentication to your specific Entra ID tenant.

Configure the OpenID Connect v1.0 provider to prevent users from other organizations from being redirected to your Keycloak

Step 4 — Configure attribute mappers

Microsoft's OIDC token includes these claims by default:

Entra ID claimDescription
oidUnique object ID for the user (stable across sign-ins)
preferred_usernameUPN or email (e.g., alice@company.com)
nameDisplay name
emailEmail — only if configured as an optional claim

The email claim is not included by default in Entra ID tokens. Add it:

  1. Azure Portal → App registrations → your app → Token configuration
  2. Add optional claim → Token type: ID → Claim: email
  3. Click Add
The email claim is optional in Entra ID — add it explicitly or use preferred_username as the email mapper source instead

In Keycloak, add attribute mappers for the built-in Microsoft provider:

  1. Identity Providers → Microsoft → Mappers → Add mapper

Email mapper:

  • Mapper type: Attribute Importer
  • Name: email
  • Claim: email (or preferred_username if you didn't add the optional claim)
  • User Attribute Name: email

First name mapper:

  • Mapper type: Attribute Importer
  • Name: firstName
  • Claim: given_name
  • User Attribute Name: firstName

Last name mapper:

  • Mapper type: Attribute Importer
  • Name: lastName
  • Claim: family_name
  • User Attribute Name: lastName

Note: given_name and family_name are only present if the user's Entra ID profile has them set. name (display name) is always present.

If given_name is blank for some users, fall back to using name with a custom mapper that splits on the first space — or accept that some accounts won't have separated first/last names

Step 5 — Configure the First Login Flow

In Identity Providers → Microsoft → Settings → First Login Flow, the default first broker login flow:

  • Prompts users to review their profile on first login
  • Detects existing Keycloak accounts with matching email and offers linking
  • Creates a new Keycloak user if no match exists

For internal employee apps where everyone already has a Keycloak account, you may want to skip the profile review and auto-link accounts. That requires a custom first login flow — beyond the scope of this guide. For most setups, the default is correct.

Set Sync Mode to force if Entra ID should be the source of truth for user attributes — useful for employee directories

Step 6 — Grant admin consent in Entra ID

If your Entra ID tenant requires admin consent for the requested permissions, individual users cannot consent for themselves during login. Until an admin pre-consents on behalf of the tenant, authentication fails — Keycloak shows a generic "An error occurred while authenticating with identity provider" error. Grant admin consent once, before users start logging in.

  1. Azure Portal → App registrations → your app → API permissions
  2. Review the listed permissions. The default User.Read (Microsoft Graph, delegated) covers the openid profile email scopes Keycloak requests.
  3. Click Grant admin consent for <your tenant> at the top of the permissions list.
  4. Confirm in the dialog. The Status column should turn to a green Granted for <your tenant> check for each permission.
Grant admin consent once at the tenant level — without it, users see a consent prompt they cannot complete and login fails

The first time a user signs in, Microsoft may show a consent screen confirming the application's requested permissions before redirecting back to Keycloak.

Once admin consent is granted, this screen is handled at the tenant level and users are no longer prompted to consent individually

Step 7 — Test the login

Open a private browser window and go to your Keycloak realm login page. A Microsoft button appears.

Microsoft's login button displays the Microsoft logo automatically — Keycloak renders it from the built-in provider metadata

After Microsoft authentication, Keycloak creates a user and shows the review profile page. Confirm the federated account: Keycloak admin → Users → find the user → Identity Provider Links tab.

The external user ID is the Entra ID object ID (oid claim) — unique per user within the tenant

Troubleshooting common issues

"AADSTS50011: The redirect URI does not match"

The redirect URI sent to Entra ID doesn't match the one registered in Azure. The exact URI must be in the app registration's Redirect URIs list. Copy it from Keycloak: Identity Providers → Microsoft → Redirect URI field. Also check that the app registration's redirect URI uses Web platform type, not SPA or Mobile.

Users from other tenants can log in when you intended single-tenant only

The built-in Microsoft provider defaults to the common endpoint, which accepts accounts from any tenant. For a stricter single-tenant setup, switch to the generic OpenID Connect v1.0 provider as described in Step 3.1.

The email attribute is blank in Keycloak

The email claim is an optional claim in Entra ID — add it via Token configuration in the Azure Portal (Step 4). Alternatively, use preferred_username as the source for the email mapper: it's the user's UPN (e.g., alice@company.com) and is always present.

"An error occurred while authenticating with identity provider"

This generic Keycloak error page (shown after returning from Microsoft) most often means admin consent was not granted for the app registration in Entra ID. When the tenant requires admin consent, users can't self-consent and the token exchange fails. Grant admin consent as described in Step 6. To confirm the root cause, check the Keycloak server log — it usually contains the underlying AADSTS65001 consent message.

"AADSTS65001: The user has not consented"

The user is seeing a consent prompt they can't complete because admin consent is required for the requested scopes. An admin must pre-consent on behalf of all users — see Step 6 for the exact steps.

Client secret expired

Entra ID client secrets have a maximum lifetime of 24 months. After expiry, token exchange fails. Rotate the secret before it expires: create a new secret in Azure, update it in Keycloak, then delete the old one.

"AADSTS700016: Application was not found in the directory"

The Client ID in Keycloak doesn't match any app in the Entra ID tenant being used for authentication. This can happen if you registered the app in one tenant but users are trying to log in from a different one. Verify the Application (client) ID in Azure Portal matches what's in Keycloak.

Production checklist

  • Client secret expiry noted and rotation reminder set
  • Client secret stored outside source control
  • Account type (single tenant vs multi-tenant) chosen deliberately and tested
  • email optional claim added in Azure token configuration, or preferred_username used as fallback
  • Attribute mappers configured for email, firstName, lastName
  • Single-tenant setups using the generic OpenID Connect v1.0 provider (Step 3.1), not the common endpoint
  • Admin consent granted in Entra ID if required by tenant policy (Step 6)
  • Tested with accounts from the expected tenant, and verified that accounts from other tenants are blocked if that's the requirement

Need help integrating Microsoft Entra ID with Keycloak?

We deliver production-ready Microsoft Entra ID + Keycloak integrations in 1–3 weeks.

Fixed-price, zero vendor lock-in, full source code ownership.

See integration packages