Keycloak Microsoft Entra ID Identity Provider Setup

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

Azure Portal New app registration page showing the Name field set to keycloak, Supported account types with three radio button options, and Redirect URI set to the Keycloak broker endpoint URL

Screenshot coming soon

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

Azure Portal app registration Overview page showing the Application client ID and Directory tenant ID values

Screenshot coming soon

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

Azure Portal Certificates and secrets page showing a newly created client secret with the Value field highlighted and a warning that the value cannot be viewed after leaving this page

Screenshot coming soon

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.

Keycloak admin console Identity Providers page showing the Microsoft provider configuration with Client ID and Client Secret fields filled in

Screenshot coming soon

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.

Keycloak admin console showing the OpenID Connect v1.0 provider form configured for a tenant-specific Microsoft Entra ID setup

Screenshot coming soon

Step 4 — Configure attribute mappers

Microsoft's OIDC token includes these claims by default:

Entra ID claim	Description
oid	Unique object ID for the user (stable across sign-ins)
preferred_username	UPN or email (e.g., [email protected])
name	Display name
email	Email — 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

Azure Portal Token configuration page showing the Add optional claim dialog with ID token type selected and email claim checked

Screenshot coming soon

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.

Keycloak Identity Provider Mappers list showing email, firstName, and lastName attribute importer mappers for the Microsoft provider

Screenshot coming soon

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.

Keycloak Microsoft Identity Provider Settings showing First Login Flow set to first broker login and Sync Mode dropdown

Screenshot coming soon

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.

Azure Portal API permissions page showing the Grant admin consent for tenant button and the Status column with green Granted check marks for the User.Read delegated permission

Screenshot coming soon

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

Microsoft consent screen for the keycloak application listing the requested permissions such as sign in and read user profile, with Accept and Cancel buttons

Screenshot coming soon

Step 7 — Test the login

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

Keycloak login page showing a Sign in with Microsoft button below the standard login form

Screenshot coming soon

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.

Keycloak User detail page Identity Provider Links tab showing a microsoft row with the Entra ID object ID as the external user ID

Screenshot coming soon

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., [email protected]) 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