Connect Keycloak to LDAP

Connect Keycloak to LDAP, configure user federation, map directory attributes and groups, secure synchronization, and troubleshoot common issues.

Type
Tutorial
Level
Intermediate
Technologies
LDAP, LDAPS, OpenID Connect
On this page

Introduction: Why Integrate LDAP with Keycloak?

LDAP integration with Keycloak is a crucial step for organizations aiming to centralize authentication, streamline access management, and leverage existing enterprise directories such as OpenLDAP or Active Directory. At its core, this integration enables Keycloak to act as a broker, mapping and managing user identities held in external LDAP systems. This approach simplifies both authentication and user lifecycle management: credentials are validated by the authoritative directory (e.g., AD), while Keycloak provides a layer of access control and supports modern federation protocols.

User federation in Keycloak refers to this model: Keycloak does not store your users, passwords, or group memberships locally but “federates” authentication and user data to the external LDAP directory. Keycloak supports multiple user federation providers within the same realm, allowing for hybrid identity scenarios. This makes configuration details, identity mapping, and lifecycle management decisions highly consequential for robustness and security.

Securing the Connection: LDAPS, TLS, and Truststore Considerations

A secure connection between Keycloak and LDAP is mandatory for production deployments. LDAP over plain sockets (LDAP, port 389, unencrypted) exposes credentials and directory queries to network interception. To protect sensitive information, always use LDAPS (LDAP over SSL/TLS, typically port 636) or LDAP with StartTLS.

Keycloak validates the authenticity of the LDAP server by verifying its TLS certificate. This relies on the server certificate being issued by a trusted Certificate Authority (CA). As a result, you must ensure that the LDAP server’s CA (or its public certificate) is present in the Java truststore used by the Keycloak server process.

Common truststore misconfigurations cause LDAPS connections to fail with errors such as SSL handshake failures or “unable to find valid certificate path to requested target.” Typical causes include missing certificates, expired CA roots, or misconfigured truststore locations. Correctly importing the LDAP CA certificate and validating the truststore’s use in the Keycloak Java runtime are key tasks during setup and maintenance.

Key Concepts: Bind DNs, User Federation, and Authentication Flow

A Bind DN is a service account distinguished name used by Keycloak to authenticate against LDAP. This account requires sufficient privileges to search the LDAP subtree that contains user objects. It does not need admin rights, but should have read rights to all user and group attributes that need to be synchronized or mapped into Keycloak.

The authentication flow involves two processes:

  • When a user attempts to log in, Keycloak performs the LDAP bind on behalf of the authenticating user, validating credentials directly against the authoritative LDAP source.
  • Neither the user’s password nor the actual authentication logic is managed by Keycloak unless users are migrated and decoupled from LDAP.

Keycloak will also fetch user attributes at login, at scheduled sync intervals, or on-demand, depending on configuration. Edit modes allow read/write or read-only access to user profiles based on LDAP permissions and operational needs.

Configuration Walkthrough: Adding an LDAP Provider in Keycloak

To connect to LDAP, you register a new User Federation provider in the Keycloak admin console. Critical parameters include:

  • Connection URL: Protocol (“ldap://” or, recommended, “ldaps://”), server hostname(s), and port.
  • Bind DN and Bind Credential: The service account and password used to authenticate search operations.
  • LDAP Vendor: Select the specific directory type (e.g., Active Directory, OpenLDAP). This tunes attribute mappings and operational logic in Keycloak’s integration.
  • Base DN: The starting point for Keycloak’s directory queries. Defines the subtree containing users/groups.
  • User Search Filter: LDAP filter to restrict scope (e.g., only enabled users).

Federation Sync Modes

Keycloak supports three main synchronization approaches:

  • Import mode: User data is copied into Keycloak’s local store at sync. Credentials always remain with LDAP but UX and session data can be partially local.
  • Periodic sync: Keycloak queries LDAP at configured intervals to refresh user and group data.
  • Just-in-time (JIT) sync: Data for a user is only loaded on first login. This minimizes upfront sync overhead but may delay initial authentication.

Each mode involves tradeoffs for freshness of data, login performance, and complexity. For example, orgs where user accounts appear and disappear frequently in LDAP may prefer periodic sync to ensure alignment.

Attribute and Group Mapping: Best Practices and Gotchas

Mapping ensures that Keycloak fields (e.g., username, email, groups) accurately reflect LDAP attributes. Attribute mappers are configured per provider and allow for fine-grained control over which LDAP fields are read into Keycloak and how they are transformed.

  • Username conflicts: If a username exists in both local Keycloak and LDAP stores, Keycloak cannot automatically merge or link these users. Attempting to link results in failure, and session/OTP data is not migrated. Account cleanup and sometimes manual or scripted migration are required to avoid confusion and access issues.
  • Attribute scoping: In multi-LDAP or hybrid environments, always scope mappers to the correct provider to avoid leaking or overwriting user information between federation sources.
  • Vendor-specific mapping: For Active Directory, certain fields like objectGUID or sAMAccountName are typically mapped to the Keycloak user ID and username fields. OpenLDAP deployments may use uid or custom identifiers.

Group mappings are similarly controlled via group mappers, which synchronize LDAP group membership to Keycloak’s roles or group model. Failures in mapping or incorrect attribute selection can result in incomplete or incorrect user profiles.

High Availability and Multiple LDAP Endpoints

For robust operation, Keycloak supports multiple LDAP server URLs in the connection settings, separated by spaces. If one server or DC is unavailable, Keycloak attempts the next in the list. This provides true failover support.

Using DNS-based round-robin for high availability is not sufficient, as Keycloak does not retry alternative IPs when an endpoint returns a connection failure (as opposed to DNS-level misrouting). Always specify multiple fully qualified LDAP URLs to ensure actual service redundancy.

Active Directory environments spanning multiple domain controllers benefit from this setup, but careful network and firewall configuration are necessary to ensure all listed endpoints are reachable and responsive.

Troubleshooting Common LDAP–Keycloak Integration Failures

Troubleshooting frequently centers around connection errors, data mapping mismatches, and sync failures. Common issues include:

  • SSL handshake failures or truststore errors: Double-check that the LDAP CA certificate is in the truststore referenced by the running Java process. Logging may show certificate path errors or handshake aborts, both indicative of missing or invalid trust roots.
  • User sync and attribute mapping failures: Ensure that LDAP filters are correct and that all required attributes exist and are readable by the Bind DN account. Attribute mapping errors can manifest as missing fields in the Keycloak user profile or misassigned group memberships.
  • Overlapping accounts: If a user attempts to log in whose username exists in both local Keycloak and LDAP, Keycloak will not merge the identities—manual intervention is necessary.
  • Mapper scoping issues: In realms with multiple user federation providers, make sure that each attribute or group mapper is explicitly scoped to the intended LDAP provider to prevent cross-provider leakage or unexpected data overwrites.

Analyzing Keycloak’s server logs, increasing debug level for user federation, and simulating explicit binds and searches with external LDAP tools assist diagnosis.

Production Hardening: Final Checklist

Before moving LDAP–Keycloak integration into production:

  • Enforce LDAPS or StartTLS for all LDAP connections to prevent credential exposure.
  • Validate truststore configuration and establish certificate renewal procedures to preempt expiry-driven outages.
  • Apply principle of least privilege to the Bind DN service account. Only grant the rights required for search and attribute read/write as needed by your chosen edit mode.
  • Test failover by simulating failure of primary LDAP endpoints and confirming user authentication and sync proceed via secondary servers.
  • Regularly review attribute and group mappers, especially when introducing new federation providers or modifying profile field requirements, to avoid scope and collision issues.
  • Monitor synchronization results and logs for errors or partial syncs, and establish alerting for recurring issues.

Keycloak LDAP integration is powerful, but requires meticulous attention to connection security, attribute scoping, identity lifecycle management, and operational monitoring to remain robust and secure throughout its lifecycle.

Sources

Related resources