How to Configure Microsoft Entra ID as a SAML Identity Provider in Keycloak

Last updated: June 2026

To set up Microsoft Entra ID as a SAML identity provider in Keycloak, create a non-gallery Enterprise Application in the Microsoft Entra admin center, configure SAML single sign-on with your Keycloak realm’s Entity ID and ACS URL, download the Federation Metadata XML, then import that metadata into Keycloak as a SAML v2.0 identity provider and add attribute mappers for email and name. That is the whole loop. Everything below is the detailed version, written for current Keycloak 26.x (the Quarkus distribution) and the current Entra admin center.

Organizations that standardize on Microsoft 365 often need their Keycloak-protected apps to accept logins from Entra ID (formerly Azure AD). SAML 2.0 is the most common protocol for this kind of cross-domain federation, and Keycloak has first-class support for it as a service provider. This guide covers the full path: creating the Enterprise Application, exporting federation metadata, importing it into Keycloak as an identity provider, setting up attribute mappers, and testing the flow end to end. By the time you finish, users in your Entra ID tenant can sign in to any Keycloak realm with their Microsoft credentials.

Prerequisites

Before starting, make sure you have:

• A running Keycloak instance on a recent release (26.x is the current line, and anything from 22 onward uses the same SAML broker UI). You can spin one up locally with the Skycloak Docker Compose Generator, or skip the server babysitting entirely with managed Keycloak hosting.
• A Microsoft Entra ID tenant with at least the Application Administrator or Cloud Application Administrator role.
• Admin access to your Keycloak realm where you want to add Entra ID as an identity provider.
• Basic SAML knowledge: terms like Entity ID, Assertion Consumer Service (ACS) URL, and NameID. If you need a refresher, the Keycloak SAML documentation is a good starting point.

You will also need your Keycloak base URL and the name of the target realm. Throughout this guide we use https://keycloak.example.com as the base URL and my-realm as the realm name. Swap in your actual values as you go.

A note on URLs: Keycloak 26.x runs on Quarkus, and its endpoints live under /realms/... and /admin/. If you are following an older tutorial that uses the legacy /auth/ base path (or mentions WildFly and standalone.xml), that distribution is end of life. None of the URLs in this guide include /auth/.

Step 1: Collect Your Keycloak SAML Endpoints

Before touching Entra ID, gather the values you will need. Keycloak exposes a SAML descriptor for each realm at a predictable URL:

https://keycloak.example.com/realms/my-realm/protocol/saml/descriptor

Open that URL in a browser. You will see an XML document containing your realm’s SAML metadata. Note two values from it:

Keep these handy. You will enter them into Entra ID in Step 2.

Note: The ACS URL above uses saml as the identity provider alias. If you plan to use a different alias (like entra-id), the ACS URL will change to match: https://keycloak.example.com/realms/my-realm/broker/entra-id/endpoint. We will confirm the exact value when we create the identity provider in Keycloak.

Step 2: Create an Enterprise Application in Entra ID

1. Sign in to the Microsoft Entra admin center.
2. Navigate to Identity > Applications > Enterprise applications.
3. Click New application.
4. Click Create your own application.
5. Enter a name (e.g., “Keycloak SAML SSO”), select Integrate any other application you don’t find in the gallery (Non-gallery), and click Create.

The application is created and you land on its overview page. Next, you will configure SAML-based single sign-on.

Step 3: Configure SAML SSO in Entra ID

From the Enterprise Application overview:

1. In the left sidebar, click Single sign-on.
2. Select SAML as the single sign-on method.

You will land on the Set up Single Sign-On with SAML page. The current admin center lays it out in five numbered cards: (1) Basic SAML Configuration, (2) Attributes & Claims, (3) SAML Certificates, (4) Set up the app, and (5) Test single sign-on. For now, configure cards 1 and 2. You will come back to card 3 for the certificate in Step 4.

Card 1: Basic SAML Configuration

Click Edit on the “Basic SAML Configuration” card and enter:

Click Save.

Important: The Reply URL must exactly match the ACS URL that Keycloak expects. If there is even a trailing slash mismatch, authentication will fail with a generic “invalid request” error.

Card 2: Attributes & Claims

Click Edit on the “Attributes & Claims” card. By default, Entra ID sends a set of claims. Verify or adjust the following:

The default NameID format is typically emailAddress. This is usually fine, but if your Keycloak realm expects a different format (like persistent or unspecified), update it here under Name identifier format.

Tip: If you want Keycloak to match Entra ID users by email (the most common approach), make sure the NameID source attribute is set to user.mail rather than user.userprincipalname. The UPN is not always a valid email address, especially in tenants with custom domains.

Assign Users and Groups

Before anyone can use this integration, assign users or groups to the Enterprise Application. This lives in the app’s sidebar, not in the numbered SAML cards, so it is easy to forget:

1. Go back to the Enterprise Application’s left sidebar and click Users and groups.
2. Click Add user/group.
3. Select the users or groups that should have access, then click Assign.

Skip this step and your testers will hit AADSTS50105: Your administrator has not granted you access the moment they try to sign in. It is the single most common “but I followed every step” failure, so do it now while you are thinking about it.

Step 4: Download the Federation Metadata XML

Back on the Single sign-on configuration page, scroll to card 3, SAML Certificates.

Click Download next to Federation Metadata XML, then save the file somewhere you can find it. You will upload it into Keycloak in the next step.

This one XML file carries everything Keycloak needs: the Entra ID Entity ID, the SSO endpoint URL, the token signing certificate, and the supported bindings. Importing it beats hand-copying values, and it is far less error prone.

Step 5: Add Entra ID as an Identity Provider in Keycloak

1. Log into the Keycloak Admin Console at https://keycloak.example.com/admin/.
2. Select your target realm from the dropdown in the top-left corner.
3. In the left sidebar, click Identity providers.
4. From the list of provider types, choose SAML v2.0.

Import Metadata

At the top of the “Add SAML provider” form, find the Import from file control (in current Keycloak you can also paste a metadata URL). Upload the Federation Metadata XML you downloaded from Entra ID.

Keycloak reads the file and auto-populates most fields, including:

• Single Sign-On service URL: the Entra ID SAML login endpoint
• Single Logout service URL: the Entra ID logout endpoint
• Validating X509 certificates: the Entra ID token signing certificate that Keycloak uses to verify assertion signatures

Configure Provider Settings

Review and adjust these fields (labels match the Keycloak 26.x admin console):

Click Add (or Save) to create the provider.

New users are created automatically the first time they log in through the first broker login flow, so there is no separate “allow create” toggle to hunt for in current Keycloak. Account creation is handled by that flow plus your chosen sync mode.

After saving, Keycloak shows the provider’s Redirect URI (the ACS endpoint). Verify it matches the Reply URL you set in Entra ID:

https://keycloak.example.com/realms/my-realm/broker/entra-id/endpoint

If it does not match, update the Reply URL in Entra ID to match exactly.

Step 6: Configure Attribute Mappers

Attribute mappers tell Keycloak how to pull user info out of the SAML assertion Entra ID sends. Without them, new users land in your realm with empty profiles: no email, no name, just a NameID. If you are running Skycloak, the same mappers work the same way, and you can cross-check provider behavior in the Skycloak docs.

In the Keycloak Admin Console:

1. Go to Identity providers > entra-id.
2. Click the Mappers tab.
3. Click Add mapper for each of the following:

Email Mapper

First Name Mapper

Last Name Mapper

Click Save after each mapper.

Debugging tip: If attribute values are not populating, use the Skycloak SAML Decoder to inspect the raw SAML response. Paste the Base64-encoded SAMLResponse from your browser’s developer tools (Network tab, look for the POST to the ACS URL) and verify the exact attribute names Entra ID is sending.

Step 7: Test the Integration

There are two ways to test:

Option A: Use the Keycloak Account Console

1. Open the Keycloak Account Console: https://keycloak.example.com/realms/my-realm/account/
2. On the login page, you should see a button labeled Microsoft Entra ID (or whatever display name you set).
3. Click it. You should be redirected to the Microsoft login page.
4. Sign in with an Entra ID user that has been assigned to the Enterprise Application.
5. After successful authentication, you should be redirected back to Keycloak, and (if this is the first login) prompted to review and confirm your account details.

Option B: Use a SAML-Initiated Login URL

You can construct a direct login URL that pre-selects the Entra ID identity provider:

https://keycloak.example.com/realms/my-realm/protocol/openid-connect/auth?client_id=account-console&response_type=code&scope=openid&redirect_uri=https://keycloak.example.com/realms/my-realm/account/&kc_idp_hint=entra-id

The kc_idp_hint=entra-id parameter tells Keycloak to skip its own login page and go straight to Entra ID.

Verify User Creation

After a successful test login, go to Users in the Keycloak Admin Console. You should see the new user with:

• The email address from Entra ID
• First and last name populated by the attribute mappers
• A federated identity link to the entra-id provider (visible under the user’s Identity Provider Links tab)

Troubleshooting

SAML integrations involve multiple moving parts. Here are the most common issues and how to resolve them.

Clock Skew Errors

Symptom: Authentication fails immediately after Entra ID redirects back. Keycloak logs show org.keycloak.saml.common.exceptions.ProcessingException with a message about assertion timing.

Cause: The clocks on your Keycloak server and Microsoft’s Entra ID servers are out of sync. SAML assertions include NotBefore and NotOnOrAfter timestamps, and Keycloak rejects assertions that fall outside a configurable tolerance.

Fix:

• Ensure your Keycloak server uses NTP for time synchronization. On most Linux systems: timedatectl set-ntp true.
• In the Keycloak Admin Console, go to Identity providers > entra-id and increase the Allowed clock skew field (in seconds). A value of 30 to 60 accommodates most environments.

Certificate Mismatch

Symptom: Keycloak logs show a signature validation error, something like Signature validation failed. No signing certificate configured.

Cause: Entra ID rotates its token signing certificates periodically. If the certificate in Keycloak does not match the one Entra ID is currently using, signature validation fails.

Fix:

1. In the Entra admin center, go to the Enterprise Application > Single sign-on > SAML Certificates and download the latest Federation Metadata XML.
2. In Keycloak, go to Identity providers > entra-id and re-import the metadata file. This updates the signing certificate.
3. Alternatively, manually copy the new Base64-encoded certificate from Entra ID and paste it into the Validating X509 Certificates field in Keycloak.

Proactive tip: Enable certificate rollover notifications in Entra ID so you are notified before a certificate expires.

NameID Format Mismatch

Symptom: Keycloak creates users but with garbled or unexpected usernames (e.g., a GUID instead of an email address), or authentication fails with a NameID policy error.

Cause: Keycloak expects one NameID format (e.g., emailAddress) but Entra ID sends another (e.g., persistent or unspecified).

Fix:

1. In Entra ID, go to Single sign-on > Attributes & Claims > Edit and check the Name identifier format. Set it to Email address if you want Keycloak to receive the user’s email as the NameID.
2. In Keycloak, go to Identity providers > entra-id and set NameID Policy Format to match. Use Email for email-based NameID, or Unspecified to accept whatever Entra ID sends.

Redirect Loop

Symptom: After clicking the Entra ID button on the Keycloak login page, you are bounced back and forth between Keycloak and Entra ID without ever completing authentication.

Cause: Usually a mismatch between the Reply URL in Entra ID and the actual ACS endpoint in Keycloak. This can also happen if the Entity ID in Entra ID does not match the Keycloak realm’s Entity ID.

Fix:

• Double-check the Reply URL in Entra ID matches the value shown in Keycloak under Identity providers > entra-id > Redirect URI.
• Verify the Entity ID in Entra ID matches the entityID in your Keycloak realm’s SAML descriptor.
• Check that the user attempting to log in has been assigned to the Enterprise Application in Entra ID.

Attributes Not Populating

Symptom: Users authenticate successfully, but their first name, last name, or email is blank in Keycloak.

Cause: The attribute names in your Keycloak mappers do not match the claim names Entra ID sends in the SAML assertion.

Fix:

1. Use the SAML Decoder tool to inspect the actual SAML response.
2. Look at the <Attribute> elements and compare their Name values against what you configured in your Keycloak mappers.
3. Update the mappers to use the exact attribute names from the assertion.

FAQ

Can I use this setup with multiple Keycloak realms?

Yes. Each realm acts as a separate SAML service provider. You will need to create a separate Enterprise Application in Entra ID for each realm (each with its own Entity ID and ACS URL), or configure a single Enterprise Application with multiple Reply URLs if all realms share the same Entity ID pattern.

How do I enable automatic account linking for existing Keycloak users?

By default, the first broker login flow prompts users to link their Entra ID identity to an existing Keycloak account if a matching email is found. If you want this to happen silently without user interaction, you can create a custom authentication flow that auto-links based on email. See the Keycloak identity broker documentation for details on customizing the first login flow.

Should I use SAML or OIDC for Entra ID integration?

Both work. SAML is the better choice when you need compatibility with enterprise security policies that mandate SAML, or when you are integrating with an Entra ID tenant that already uses SAML extensively. OIDC is generally simpler to configure and debug. If you do not have a specific reason to use SAML, consider OIDC as an alternative. For a deeper look at identity provider options in a managed Keycloak environment, see the Skycloak identity providers feature.

Why am I getting an AADSTS error when I try to log in?

AADSTS errors come from Entra ID, not Keycloak, so the message tells you exactly what failed. AADSTS50105 means the user is not assigned to the Enterprise Application, so fix it under Users and groups. AADSTS650056 or AADSTS75011 usually point to a mismatched Identifier (Entity ID) or Reply URL between Entra and Keycloak. Copy both values fresh from the Keycloak provider page and paste them back into Entra to rule out typos.

Can I import the Entra ID metadata by URL instead of a file?

Yes. Entra ID publishes a tenant federation metadata URL in the form https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>, and current Keycloak accepts a metadata URL in the import control. The URL is handy because Keycloak can refresh the signing certificate from it, which sidesteps the manual re-import dance every time Entra rotates its certificate. If your Keycloak host blocks outbound calls to Microsoft, fall back to the downloaded XML file.

How do I fix a SAML signature or certificate validation failure?

Signature failures almost always mean the certificate in Keycloak no longer matches the one Entra ID is signing with, usually after a certificate rollover. Re-import the Federation Metadata XML (or metadata URL) so Keycloak picks up the current Validating X509 certificate. If you previously pasted a certificate by hand, replace it with the new Base64 value from card 3, SAML Certificates. Enabling Entra ID certificate-expiry notifications saves you from finding out the hard way.

Conclusion

That is Microsoft Entra ID running as a SAML identity provider in Keycloak. Users from your Entra ID tenant can now sign in to Keycloak-protected apps with their existing Microsoft credentials, and their email, first name, and last name flow in automatically through the attribute mappers.

Three things keep this integration healthy: keep the Entity ID and ACS URL identical on both sides, configure the attribute mappers so profiles are complete, and watch certificate expiry so a silent rollover does not take logins down at 2 a.m.

If you would rather configure SSO than babysit a Keycloak server, managed Keycloak hosting from Skycloak ships with identity provider support ready to go. Compare plans on the pricing page, browse the Skycloak docs for other IdP integrations, or keep the SAML Decoder open in a tab the next time an assertion misbehaves.