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

Last updated: March 2026

---

Organizations that standardize on Microsoft 365 often need their Keycloak-protected applications 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 walks through the full configuration: creating an Enterprise Application in Entra ID, exporting federation metadata, importing it into Keycloak as an identity provider, setting up attribute mappers, and testing the end-to-end flow. By the end, users in your Entra ID tenant will be able to authenticate into any Keycloak realm using their Microsoft credentials.

Prerequisites

Before starting, make sure you have:

• A running Keycloak instance (version 22 or later). You can spin one up locally with the Skycloak Docker Compose Generator, or use a managed Keycloak host like Skycloak.
• 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 — understanding of 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 to know your Keycloak base URL and the name of the target realm. Throughout this guide, we will use https://keycloak.example.com as the base URL and my-realm as the realm name. Replace these with your actual values.

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:

Value	Where to Find It
Entity ID	The entityID attribute on the root <EntityDescriptor> element. Typically https://keycloak.example.com/realms/my-realm
ACS URL	The Location attribute on the <AssertionConsumerService> element. Typically https://keycloak.example.com/realms/my-realm/broker/saml/endpoint

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 see the Set up Single Sign-On with SAML page with five numbered sections. Configure sections 1 and 2:

Section 1: Basic SAML Configuration

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

Field	Value
Identifier (Entity ID)	https://keycloak.example.com/realms/my-realm
Reply URL (ACS URL)	https://keycloak.example.com/realms/my-realm/broker/entra-id/endpoint
Sign on URL	(leave blank)
Relay State	(leave blank)
Logout URL	https://keycloak.example.com/realms/my-realm/protocol/saml

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.

Section 2: Attributes & Claims

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

Claim Name	Source Attribute	SAML Attribute Name
Unique User Identifier (NameID)	user.userprincipalname	(NameID — this is the Subject)
email	user.mail	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
givenname	user.givenname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
surname	user.surname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

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.

Section 3: Assign Users and Groups

Before anyone can use this SSO integration, you need to assign users or groups:

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.

Without this step, users will get an “AADSTS50105: Your administrator has not granted you access” error when they attempt to sign in.

Step 4: Download the Federation Metadata XML

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

Click Download next to Federation Metadata XML. Save this file somewhere accessible — you will upload it into Keycloak in the next step.

This XML file contains everything Keycloak needs: the Entra ID Entity ID, SSO endpoint URL, signing certificate, and supported bindings.

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. Click Add provider and select SAML v2.0.

Import Metadata

At the top of the “Add SAML provider” form, you will see an Import from file option. Click it and upload the Federation Metadata XML you downloaded from Entra ID.

Keycloak will auto-populate most fields from the metadata, including:

• Single Sign-On Service URL — the Entra ID SAML endpoint
• Single Logout Service URL — the Entra ID logout endpoint
• Validating X509 Certificates — the Entra ID token signing certificate

Configure Provider Settings

Review and adjust these fields:

Field	Recommended Value	Notes
Alias	entra-id	Used in the ACS URL. Must match what you entered in Entra ID.
Display Name	Microsoft Entra ID	Shown on the Keycloak login page
Enabled	ON
Trust Email	ON	Entra ID verifies email addresses, so Keycloak can skip re-verification
First Login Flow	first broker login	Default flow that handles account linking and creation
NameID Policy Format	Email	Must match what Entra ID sends. Use Unspecified if unsure.
Principal Type	Subject NameID
Allow create	ON	Allows Keycloak to auto-create accounts for new Entra ID users
HTTP-POST Binding Response	ON
Want AuthnRequests Signed	ON	Signs the SAML request sent to Entra ID

Click Save.

After saving, Keycloak will display the provider’s Redirect URI (also called the ACS URL). Verify that it matches the Reply URL you configured 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 extract user information from the SAML assertion that Entra ID sends. Without them, new users will be created with empty profiles.

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

Field	Value
Name	email
Sync mode override	inherit
Mapper type	Attribute Importer
Attribute Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
User Attribute Name	email

First Name Mapper

Field	Value
Name	firstName
Sync mode override	inherit
Mapper type	Attribute Importer
Attribute Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
User Attribute Name	firstName

Last Name Mapper

Field	Value
Name	lastName
Sync mode override	inherit
Mapper type	Attribute Importer
Attribute Name	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
User Attribute Name	lastName

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.

Conclusion

You now have Microsoft Entra ID configured as a SAML identity provider in Keycloak. Users from your Entra ID tenant can authenticate into Keycloak-protected applications using their existing Microsoft credentials, with attributes like email, first name, and last name automatically mapped.

The key points to remember: keep the Entity ID and ACS URL consistent between both systems, configure attribute mappers so user profiles are complete, and monitor certificate expiration to avoid unexpected outages.

If you want to skip the infrastructure management and focus on configuration, Skycloak provides fully managed Keycloak instances with SSO and identity provider support built in. You can also explore the Skycloak documentation for guides on other identity provider integrations and SAML debugging tools.