Want to integrate Microsoft Entra ID with Keycloak for secure single sign-on (SSO)? This guide simplifies the process of setting up Entra ID as a SAML Identity Provider (IdP) in Keycloak. Here’s what you’ll achieve:
- Centralize user authentication for better security and easier access management.
- Enable SSO, so users log in once and access all connected apps seamlessly.
- Configure user attributes like email, name, and groups for smooth data exchange.
Key Steps:
- Prepare Systems: Ensure admin access to both Entra ID and Keycloak, enable HTTPS connectivity, and gather required details (e.g., tenant ID, Keycloak URL).
- Set Up Keycloak: Create a SAML client, configure attribute mapping (email, name, groups), and apply security settings like signing and encryption.
- Configure Entra ID: Register Keycloak as an enterprise application, set SAML parameters (e.g., Entity ID, Reply URL), and upload Keycloak metadata.
- Test & Secure: Validate SSO and Single Logout (SLO), troubleshoot errors, and apply best practices like MFA and short-lived tokens.
Quick Overview of Best Practices:
- Use HTTPS and enable digital signatures for secure communication.
- Map user attributes correctly to avoid login issues.
- Regularly update certificates to prevent disruptions.
Looking for a hassle-free solution? Managed services like Skycloak can handle the setup, monitoring, and maintenance for you.
Prerequisites and Setup Requirements
Before diving into the configuration, make sure you meet the necessary access levels, network setup, and system prerequisites. Missing any of these could lead to authentication issues or incomplete integration.
Required Accounts and Permissions
To get started, you’ll need administrative access to both the Entra ID portal and Keycloak. Without these permissions, you won’t be able to configure the systems or establish trust between them.
Additionally, ensure you have Cloud Application Administrator privileges in Entra ID. This role is essential for tasks like registering applications, setting up SAML configurations, and managing enterprise applications. Regular user accounts won’t have the permissions required to complete these steps.
Another key requirement: all users who will authenticate through this integration must have email addresses registered in Entra ID. This is crucial because Keycloak uses email addresses as the primary identifier for user mapping and attribute exchange during SAML authentication.
Lastly, gather the following details before you begin:
- Entra ID tenant information (e.g., tenant ID, domain name, and any custom configurations)
- The base URL for your Keycloak instance
Network and Connectivity Requirements
For the integration to work seamlessly, you’ll need bidirectional HTTPS connectivity between Keycloak and Entra ID. This ensures secure communication and the exchange of SAML assertions over encrypted HTTPS connections.
Here’s what to check:
- Your Keycloak instance must be able to make HTTPS requests to Entra ID on port 443 (the default HTTPS port). This connection allows Keycloak to validate SAML responses and retrieve user data during authentication.
- Entra ID must also be able to reach your Keycloak instance via HTTPS. This is particularly important for enabling single logout functionality. Without this, users might remain logged into some applications even after signing out of others.
For end users, their workstations must have access to both Entra ID’s login screens and SAML endpoints. During the authentication process, users’ browsers will need to redirect between Entra ID for login and Keycloak for application access.
Lastly, confirm that no firewalls, proxies, or security policies are blocking HTTPS traffic on port 443 between Keycloak and Entra ID.
US Format Considerations
When configuring timestamps, session timeouts, and user attributes, make sure your settings adhere to US formatting standards. Here are some specifics to keep in mind:
- Use the MM/DD/YYYY format for dates, such as certificate expiration dates or user account creation timestamps.
- Apply the 12-hour clock with AM/PM indicators for time-based settings like session timeouts or audit logs.
- For numbers, use comma-separated formatting for thousands (e.g., 1,000 instead of 1.000).
- Display currency attributes in US dollar format, with a dollar sign prefix (e.g., $1,000.00).
These formatting details ensure consistency across your system and create a familiar experience for US-based users and administrators. With everything in place, you’re ready to configure Keycloak for SAML integration.
Setting Up Keycloak for SAML Integration
To integrate Keycloak with Entra ID as your SAML Identity Provider (IdP), you’ll need to create a SAML client, map user attributes, and implement key security settings to safeguard your authentication process.
Creating a SAML Client in Keycloak
Start by selecting your desired realm in Keycloak, then navigate to Clients and click Create.
- Use your application’s entity ID as the Client ID. This is typically formatted as a URL, like
https://your-app.example.com/saml/metadata. This ID is crucial – it helps both Keycloak and Entra ID identify your application during authentication. - Set the Client Protocol to SAML.
- Configure the Client SAML Endpoint (also called the Assertion Consumer Service URL). This must match the value you’ll configure in Entra ID.
- Define Valid Redirect URIs, such as
https://app.example.com/saml/SSO, to ensure SAML responses are only sent to authorized endpoints. - Set the Master SAML Processing URL to your application’s base SAML endpoint, for example,
https://app.example.com/saml.
Once the client is created, download the metadata XML file. This file contains signing certificates and endpoint URLs needed to configure Entra ID.
Next, you’ll need to set up attribute mapping to ensure user data is transferred correctly.
Configuring User Attribute Mapping
Accurate attribute mapping is essential for smooth user authentication and profile consistency. Without proper mapping, users might encounter login problems or incomplete profile details.
Create mappers for the attributes your application needs. Common attributes include email, first name, last name, and group memberships. These mappers tell Keycloak how to interpret the SAML attributes it receives from Entra ID.
For Entra ID, you’ll typically map the following attributes:
- Username:
user.userprincipalname - First Name:
user.givenname - Last Name:
user.surname - Email:
user.mail - Groups:
user.groups[Security Groups]
After mapping these attributes, the next step is to secure your integration by configuring the recommended security settings.
Security Configuration
To enhance the security of your SAML integration, apply these recommended settings:
| Setting | Recommended Value | Impact |
|---|---|---|
| Sign Documents | ON | Ensures all SAML messages are digitally signed for authenticity. |
| Sign Assertions | ON | Adds an extra signature to the assertion for added security. |
| Client Signature Required | ON | Requires the Service Provider (SP) to sign authentication requests. |
| Force POST Binding | ON | Uses HTTP POST for all bindings, avoiding sensitive data in URLs. |
| Front Channel Logout | ON | Logs users out of all applications in the session for added security. |
Set the Name ID Format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. This ensures users are identified by their email address across both systems, minimizing authentication errors.
If your organization handles sensitive data or operates in a regulated environment, consider enabling Encrypt Assertions. This adds XML encryption to SAML assertions, offering an additional layer of security.
The Force POST Binding setting ensures sensitive authentication data stays out of server logs or browser history, while Front Channel Logout guarantees that users are logged out of all connected apps when they end their session. These features are critical for maintaining security in single sign-on environments.
With these configurations, your Keycloak instance is prepared to work with Entra ID as a SAML IdP. The next step is setting up the Entra ID side to finalize the trust relationship between the two systems.
Configuring Entra ID as SAML Identity Provider
After setting up your Keycloak instance, the next step is to configure Entra ID to recognize Keycloak as a trusted SAML service provider. This setup involves creating an enterprise application, adjusting SAML settings, and exchanging metadata between the two systems. These steps establish the trust required for secure SAML communication.
Registering Keycloak as an Enterprise Application
To begin, log in to the Microsoft Entra admin center and navigate to the Enterprise Applications section. Click on New application to start the registration process.
Since Keycloak isn’t typically available in the application gallery, choose the option to create your own application. Select Integrate any other application you don’t find in the gallery (Non-gallery) to create a custom SAML integration.
Assign a name to your application, such as Keycloak SAML Integration, to make it easy to identify in your enterprise application list. Once the application is created, go to the Single sign-on section and select SAML as the authentication method.
Configuring SAML Settings in Entra ID
In the Basic SAML Configuration section, you’ll need to set the Identifier (Entity ID) to match the Client ID in Keycloak. This is usually a URL, such as https://your-app.example.com/saml/metadata, and it establishes the trust relationship between the systems. Set the Reply URL (Assertion Consumer Service URL) to the Keycloak endpoint where SAML responses will be processed. This URL must align with the Client SAML Endpoint configured in Keycloak.
Next, configure the Attributes & Claims section to ensure proper user data mapping. Use the following settings:
- Name ID format:
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress - Email Address: map to
user.mail - Given Name: map to
user.givenname - Surname: map to
user.surname - Groups: configure the group claim to include only groups assigned to the application (using Group ID as the source attribute).
Finally, upload the Keycloak metadata XML file that you downloaded earlier to complete this configuration.
Downloading Entra ID Metadata
To validate SAML assertions in Keycloak, download the Entra ID metadata. Navigate to the Single sign-on configuration page and locate the SAML Certificates section.
You’ll have two options: either copy the App Federation Metadata URL, which provides a live link to the current metadata, or download the Federation Metadata XML file directly. The URL option is often preferred because it automatically reflects updates like certificate renewals or configuration changes.
Once this is done, assign users or groups to the application. Go to the Users and Groups section and add those who should have access to authenticate through this SAML integration.
The metadata you download includes critical details like signing certificates, SSO service URLs, and other technical information Keycloak needs to validate SAML assertions from Entra ID. Keep this metadata secure, as it plays a vital role in your identity provider setup. With Entra ID configured, you can now import the metadata into Keycloak and test the integration.
Completing Integration and Testing
Wrap up the integration process by importing the Entra ID metadata into Keycloak and thoroughly testing the authentication setup.
Importing Entra ID Metadata into Keycloak
Start by accessing your Keycloak admin console. From the left sidebar, navigate to Identity Providers, click Add provider, and select SAML v2.0 from the dropdown. This action will create a new SAML identity provider configuration where you can bring in your Entra ID metadata.
There are two ways to import the metadata:
- Using the Metadata URL: Paste the App Federation Metadata URL you obtained from Entra ID into the Import from URL field. This method is recommended because it ensures automatic updates if Microsoft modifies certificates or endpoints. Once pasted, click Import, and Keycloak will automatically populate the required configuration fields.
- Uploading the Metadata File: If you have downloaded the Federation Metadata XML file from Entra ID, you can upload it directly. Click Select file, choose the XML file, and Keycloak will parse it to populate fields like the Single Sign-On Service URL, signing certificates, and entity ID.
After importing, double-check the settings. The Single Sign-On Service URL should point to Microsoft’s SAML endpoint, often formatted as https://login.microsoftonline.com/[tenant-id]/saml2. Also, ensure the Name ID Policy Format is set to Email, matching the configuration in Entra ID.
Next, configure the Attribute Mapping section to sync user data between Entra ID and Keycloak. Map the email attribute for user identification and include mappings for first name, last name, and any group memberships you need to synchronize.
Once everything is configured, proceed to test the authentication setup.
Testing SSO Authentication Flow
With the metadata imported, it’s time to test the Single Sign-On (SSO) flow. Ensure the test user exists in Entra ID and has been assigned to the enterprise application. Then, go to the application that uses Keycloak for authentication and look for the Login with Entra ID SSO button (or a similar option).
Click the login button, enter the test user’s Entra ID credentials, and complete any required multi-factor authentication on Microsoft’s login page. After successful authentication, Microsoft will redirect you to Keycloak with a SAML assertion containing the user’s details.
If everything is set up correctly, you should be logged into your application and able to access the user profile or dashboard. If authentication fails, check for mismatched signing certificates or unsynchronized system clocks. Additionally, ensure the Name ID format matches between the two systems to avoid user attribute issues.
Setting Up SAML Single Logout
After confirming SSO functionality, configure and test Single Logout (SLO). This feature ensures that logging out from one application ends the session across all connected applications.
In Keycloak, go back to the SAML identity provider configuration and locate the Fine Grained SAML Endpoint Configuration section. Set the logout URLs to your application’s logout endpoint, which typically looks like https://your-app.example.com/saml/logout or something similar. These URLs direct Keycloak where to send logout requests when a user initiates SLO.
In the Advanced Settings, enable Front Channel Logout if your applications support it. This approach uses browser redirects to propagate logout requests across all connected applications. However, be aware that changes in browser behavior, especially around third-party cookies, may affect its reliability.
Test the SLO functionality by logging into your application through the SAML SSO flow. Then, initiate a logout and verify that the system redirects through all connected applications, terminating active sessions before landing on a logout confirmation page. If the process fails, ensure all applications’ logout endpoints are correctly configured.
For added security, configure logout request signing. Enable the Sign Logout Requests option in Keycloak, and ensure Entra ID is set up to validate these signatures using the appropriate certificates.
Troubleshooting and Best Practices
Once you’ve set up your integration, keeping it running smoothly and securely is key. While SAML integrations are powerful, they’re not immune to hiccups. Knowing how to handle common issues and implementing solid security measures can help you maintain a dependable authentication system.
Common Configuration Errors
Even after thorough testing, some configuration errors can block proper authentication. Here are a few frequent culprits:
- “Found an Attribute element with duplicated Name” Error: This happens when role attributes are duplicated. To fix it, turn the Single Role Attribute setting to ‘On’ in your Keycloak client scopes.
- AADSTS50034 Error: This error means the user account doesn’t exist in Azure Active Directory. It’s usually caused by a mismatch between the NameID attribute sent by Keycloak and what Entra ID expects. Double-check that your Keycloak attribute mapping is sending the correct email format tied to an existing user account.
- Invalid Digest Value: This error can completely halt SSO. It’s often caused by XML canonicalization issues. Make sure your XML signing configurations are aligned across systems.
- Cookie Not Found: Common in Kubernetes clusters using nginx ingress controllers, this issue often stems from cookie domain configurations and browser security contexts. Ensure your cookie settings match your deployment setup, and use secure cookie flags.
- SAML Logout Issues: If sessions remain active in Entra ID after users log out, it could allow unintended logins. To address this, disable HTTP-POST Binding since Entra ID only supports redirect binding for logout.
- Missing RelayState Parameter: This error occurs when the identity provider doesn’t return the RelayState parameter, breaking the flow and preventing users from reaching their intended destination. Ensure both Keycloak and Entra ID are correctly configured to handle RelayState parameters.
Security Best Practices
To safeguard your SAML integration, it’s crucial to address potential vulnerabilities. The table below outlines common risks and how to tackle them:
| Vulnerability | Risk and Cause | How to Mitigate |
|---|---|---|
| Replay Attack | Intercepted SAML messages reused due to long assertion lifespan | Use short-lived tokens and invalidate assertions after use |
| Assertion Manipulation | Altered attributes in SAML messages due to missing digital signatures | Add digital signatures to all SAML messages |
| XML External Entity (XXE) | Exploitation of XML parsers processing external entities | Disable DTD processing and enforce strict input validation |
| Email Forwarding Attack | Unauthorized access due to insufficient tenant separation | Validate attributes and enforce strong digital signatures |
Stay on top of certificate management by monitoring expiration dates and renewing certificates before they expire. Store private keys securely – hardware security modules are a great option for production environments.
Enable multi-factor authentication (MFA) in Entra ID for all users accessing SAML-connected apps. This adds an extra layer of security against compromised credentials.
When validating assertions, confirm digital signatures using the public certificate from the metadata. Check the Recipient attribute to ensure assertions are intended for your application, and verify the NotBefore and NotOnOrAfter timestamps to block expired or premature assertions.
For secure communication, always use TLS v1.2 or higher for SAML exchanges. Make sure assertions are sent over HTTPS, and use unique RequestID values for each AuthnRequest to prevent CSRF attacks.
If you’re working in a multi-tenant environment, enforce strict separation by assigning specific domains to each tenant. Ensure users’ email addresses correspond to their designated domains. Additionally, implement comprehensive logging to track authentication attempts, failed logins, and security events – this helps maintain a strong audit trail.
For organizations overwhelmed by these challenges, managed services can offer a hassle-free solution.
Skycloak Managed Service Benefits
Managing SAML integrations between Entra ID and Keycloak can get complicated, from the initial setup to ongoing maintenance. That’s where Skycloak’s managed services come in. They provide fully managed Keycloak hosting with pre-configured IAM setups tailored for enterprise integrations.
“Outstanding customer service and assistance!” – Glen, Construction Industry Employee
Skycloak simplifies the technical side of things, addressing common issues like XML signature validation, secure cookie handling, and attribute mapping. Their pre-built IAM setups for Microsoft Entra ID integration help avoid errors like AADSTS50034 or invalid digest values.
If you run into complex problems, their expert consulting team is ready to help, saving you time on troubleshooting. Plus, they make transitioning from existing Keycloak instances seamless, with data migration that preserves your current configurations and user data.
Conclusion
To set up secure single sign-on, ensure that Keycloak and Entra ID are configured with matching SAML settings. This involves creating a SAML client in Keycloak with accurate attribute mapping and registering Keycloak as an enterprise application in Entra ID with corresponding configurations. The exchange of metadata between these platforms establishes the trust necessary for authentication.
This process demands careful attention to detail. Key areas like XML signature validation, cookie domain settings, certificate management, and security configurations must be handled with precision to ensure a stable and secure integration.
For organizations aiming to simplify this setup, Skycloak’s managed service provides a convenient solution. It’s a practical choice for those looking to streamline the integration process.
FAQs
What security measures should I consider when configuring Entra ID SAML in Keycloak as an Identity Provider (IdP)?
When configuring Entra ID as a SAML Identity Provider in Keycloak, keeping security at the forefront is essential to safeguard your authentication processes.
- Validate SAML signatures thoroughly to confirm the integrity and authenticity of exchanged data. Avoid depending on the signature’s position within the XML structure, as this can introduce vulnerabilities.
- Implement strict validation for attributes and assertions to block unauthorized access and minimize the risk of data tampering.
- Stay proactive with security by regularly updating Keycloak. Ensure you address any known vulnerabilities and apply security patches as soon as they’re available.
Taking these steps helps establish a more secure and dependable SAML integration.
What are some common issues with setting up Entra ID as a SAML Identity Provider in Keycloak, and how can I troubleshoot them?
Common hiccups during Entra ID and Keycloak SAML integration often stem from metadata mismatches, certificate issues, or clock synchronization problems. Here’s how you can address these:
- Match the details precisely: Ensure the EntityID, Reply URL, and certificate information are identical between Entra ID and Keycloak. Expired or mismatched certificates are a common culprit.
- Check time synchronization: Make sure the system clocks for both Entra ID and Keycloak are aligned. Even slight discrepancies can cause assertion validity errors.
- Inspect SAML assertions: Use debugging tools to examine SAML assertions and responses for errors like signature problems or attribute mismatches.
If these steps don’t resolve the issue, dive into system logs or activate debug mode in Keycloak. Pinpointing misconfigurations through detailed logs can often reveal the root cause and help you get things running smoothly.
What are the advantages of using Skycloak to manage Entra ID and Keycloak SAML integrations?
Using Skycloak to handle Entra ID and Keycloak SAML integrations comes with several advantages. First, it streamlines the setup process by taking care of the technical details involved in SAML configuration. This saves your team both time and effort, allowing them to focus on other priorities. Second, Skycloak offers ongoing management, including regular updates, security patches, and monitoring. This means your identity federation remains secure and consistently up-to-date without additional workload.
Skycloak also helps minimize risks tied to misconfigurations and security gaps by adhering to best practices. By entrusting these tasks to specialists, your organization can concentrate on its main goals while benefiting from a scalable and secure identity management solution.