What Is LDAP Integration in Keycloak?
Large companies already have thousands of employee accounts sitting in a corporate directory long before Keycloak ever enters the picture. LDAP integration is how Keycloak plugs directly into that existing directory instead of asking everyone to create a brand-new account.
Imagine a company that has kept a single, official employee roster in one filing cabinet for the past fifteen years — every new hire’s name, department, and badge number recorded there, and every departure removed from it. When the company adopts a new building security system, the smart move isn’t recreating that entire roster by hand in the new system’s own separate database. Instead, the new system is simply configured to check the existing filing cabinet directly whenever someone badges in. Keycloak’s LDAP integration works exactly this way for user accounts: rather than duplicating a company’s existing employee directory into Keycloak’s own database, Keycloak connects straight to it and checks it directly.
1What Is LDAP Integration?
The foundation everything else in this guide builds on.
LDAP stands for Lightweight Directory Access Protocol — a long-established standard many organizations use to store and look up information about people, most commonly employees, in a structured directory. Popular systems built on this standard include Microsoft’s Active Directory, widely used inside corporate networks. LDAP integration in Keycloak, more formally called user federation, is the feature that lets a realm authenticate users directly against such an existing directory, instead of requiring every user to be manually recreated inside Keycloak’s own built-in user store.
Think of LDAP integration like a new gym that agrees to accept your existing company ID badge for entry, rather than making you sign up for a brand-new membership card. The gym doesn’t need to keep its own separate copy of your personal details — it simply checks your existing, already-trusted badge against the company’s system each time you walk in.
This matters enormously for organizations, because employee directories are often the definitive, carefully maintained source of truth about who works there — who’s been hired, who’s left, and what department someone belongs to. Duplicating all of that manually into a second system invites the two records to quietly drift out of sync over time.
No Duplicate User Database
Users continue to live in the existing directory rather than being manually recreated inside Keycloak.
Direct Credential Checking
Login attempts are verified against the directory’s own stored credentials.
Single Source of Truth
Changes made in the directory — new hires, departures, updated details — are reflected through Keycloak too.
Standards-Based
LDAP is a long-standing, widely supported protocol, not something unique to Keycloak.
LDAP integration is configured per realm — one realm might federate with a corporate directory for employees, while a completely different realm serving external customers manages its own separate, local user accounts entirely.
2LDAP Integration vs. Local Users vs. Identity Brokering
Keycloak offers a few different ways to source user identities — knowing which is which avoids real confusion later.
Keycloak supports several distinct approaches to where a user’s identity actually “lives,” and LDAP integration is only one of them. Understanding the alternatives makes clear exactly what problem LDAP integration is solving.
Local users are like a small independent shop that keeps its own membership list — the shop itself owns and manages every record directly. LDAP integration is like the gym checking your existing company badge, as described above — Keycloak reads from an existing directory it doesn’t own. Identity brokering is different again — it’s like accepting someone else’s passport rather than a company badge at all, trusting an entirely separate identity provider (like “Sign in with Google”) to vouch for the person instead.
| Approach | Where Identity Lives | Typical Use Case |
|---|---|---|
| Local Users | Directly inside Keycloak’s own database | Customer-facing apps with no pre-existing directory |
| LDAP Integration (User Federation) | An existing external directory, like Active Directory | Internal enterprise apps used by employees |
| Identity Brokering | A separate, external identity provider | Social login or trusting another organization’s identity system |
LDAP integration and identity brokering can look similar from a distance — both let Keycloak avoid recreating identities from scratch — but LDAP integration checks credentials against a directory Keycloak queries directly, while brokering redirects the user entirely to a separate system that handles the login itself.
3The Building Blocks of an LDAP Integration
What actually gets configured when connecting a realm to an existing directory.
Connection Settings
The directory server’s address and the secure connection details Keycloak uses to reach it.
Bind Credentials
A dedicated account Keycloak itself uses to log into the directory and search for user records.
Search Base and Filters
Rules defining exactly where in the directory’s structure to look, and which entries actually count as users.
Attribute Mappers
Rules translating the directory’s own field names into the attributes Keycloak expects, like matching “mail” to an email field.
Bind credentials are like giving the gym’s front desk a special staff pass that lets them check the company badge system, without that pass letting them impersonate any actual employee. Attribute mappers are like a translation sheet reminding the front desk that the company system labels a phone number “contact_no” while the gym’s own forms call it “phone.”
The bind account used to query the directory should be given the narrowest permissions genuinely needed — typically just enough to search and read basic user entries, not broad administrative rights over the whole directory.
4How LDAP Integration Works Internally: The Login Flow
Tracing what actually happens the moment a federated user tries to log in.
The User Submits Credentials to Keycloak’s Hosted Login Page
From the user’s perspective, this looks identical to a normal login — nothing about the experience reveals the account lives elsewhere.
Keycloak Searches the Directory for a Matching Account
Using its configured bind credentials, Keycloak looks up the entered username inside the connected directory.
The Directory Itself Verifies the Password
Rather than storing or checking the password itself, Keycloak asks the directory to confirm the submitted password is correct for that account.
Keycloak Issues a Token as Usual
Once the directory confirms the credentials are valid, Keycloak proceeds exactly as it would for any other successful login, issuing tokens as normal.
sequenceDiagram
participant U as User
participant K as Keycloak
participant L as LDAP Directory
U->>K: Submit username and password
K->>L: Search for matching user entry
L-->>K: Return matching entry, if found
K->>L: Verify submitted password against that entry
L-->>K: Confirm valid or invalid
K-->>U: Issue token (if valid) or show login error
Because password verification happens against the directory itself rather than a Keycloak-stored copy, an employee’s existing corporate password — and any password rules or restrictions already enforced by that directory — continue to apply exactly as before.
5Common LDAP Sync Modes
Keycloak offers a few different levels of how closely it keeps its own local copy of directory data in step.
Read-Only
Keycloak reads user data from the directory but never writes changes back — any profile edits must happen in the directory itself.
Writable
Changes made through Keycloak, such as an updated attribute, are written back into the connected directory as well.
Unsynced
Keycloak still authenticates against the directory for login, but any changes made in Keycloak are stored only locally, not sent back to the directory.
Read-Only in Practice
A company whose HR system is the strict, official source of truth for employee data typically chooses read-only mode, ensuring Keycloak never accidentally becomes a second, conflicting place where employee details can be edited.
Unsynced in Practice
An organization that wants to authenticate against an existing directory but also let Keycloak store a few extra, application-specific attributes not tracked in the directory at all often uses unsynced mode for that added flexibility.
Writable mode grants Keycloak the ability to modify a potentially sensitive, centrally managed corporate directory — this should be a deliberate decision made with the directory’s own administrators, not a default left unexamined.
6Periodic Synchronization and Caching
Keycloak doesn’t necessarily query the directory fresh for every single interaction — understanding the caching layer matters.
To avoid overwhelming the directory server with constant lookups, Keycloak typically caches a local copy of federated user information for a configurable period, refreshing it either periodically or on demand, rather than always re-querying the directory for every single request.
flowchart LR
A[Scheduled Sync Triggered] --> B[Keycloak Queries LDAP Directory]
B --> C[New and Updated Users Cached Locally]
C --> D[Removed Users Marked or Cleaned Up]
D --> E[Local Cache Used Until Next Sync]
E --> A
It’s similar to a library that photocopies the latest version of a shared reference book once a day rather than walking to the original archive room every single time someone asks a question — fast enough for practical use, while still staying reasonably current.
Because of this caching behavior, a change made directly in the source directory — like disabling a departing employee’s account — may take a short while to be reflected inside Keycloak, depending on the configured sync schedule.
7Mapping Directory Attributes to Keycloak Fields
Different directories often label the same kind of information differently — mappers bridge that gap.
A corporate directory might label a user’s email address, full name, or department using its own internal field names, which don’t necessarily match what Keycloak expects out of the box. Attribute mappers define exactly how each directory field should translate into a corresponding Keycloak user attribute.
Username
Often mapped from the directory’s own unique login identifier field.
Email Address
Commonly mapped from a standard mail-related field already present in most directories.
Full Name
Mapped from a display-name or combined first-and-last-name field stored in the directory.
Group Membership
Directory group memberships can be mapped so they translate into Keycloak groups or roles automatically.
Mapping directory group memberships into Keycloak roles is a particularly powerful pattern, letting an employee’s existing department or team membership in the corporate directory automatically translate into the correct application permissions.
8Security Considerations for LDAP Integration
Connecting to a sensitive, often company-wide directory introduces some specific responsibilities.
Unencrypted Directory Connections
Communicating with the directory over an unencrypted connection risks exposing credentials and data in transit.
Overprivileged Bind Account
A bind account with excessive permissions over the directory creates unnecessary risk if that account is ever compromised.
Stale Cached Data
An infrequent sync schedule can leave Keycloak trusting outdated information, such as a disabled account that hasn’t yet been reflected.
Uncontrolled Writable Access
Writable sync mode gives Keycloak the ability to modify a shared, sensitive directory — a capability that needs careful oversight.
Always use an encrypted connection to the directory server, use a dedicated bind account with the narrowest permissions the integration actually needs, and set a sync schedule that balances timeliness against load on the directory server.
9Design Patterns and Anti-Patterns
Lessons learned from real-world LDAP integration deployments.
Problem
Configuring the bind account with broad administrative privileges over the entire directory, far beyond what searching and reading user records actually requires.
Why It’s Harmful
If Keycloak’s configuration or credentials are ever compromised, an overprivileged bind account could allow far more damage to the organization’s core directory than the integration ever needed to be capable of.
Correct Approach
Create a dedicated, narrowly scoped service account specifically for this integration, granted only the minimal read (and, if genuinely needed, limited write) permissions required.
Problem
Connecting to the directory server over an unencrypted connection, especially across a network segment that isn’t fully trusted.
Why It’s Harmful
Credentials and personal data exchanged during directory queries could be exposed to anyone able to observe traffic on that network path.
Correct Approach
Always configure the connection to use an encrypted transport, treating directory traffic with the same seriousness as any other channel carrying credentials.
Design Pattern: Directory as Source of Truth, Keycloak as Consumer
Keeping the directory as the single, authoritative place where employee accounts are created, updated, and disabled — with Keycloak simply reading from it — avoids the confusion and drift that comes from having two systems that both think they own the same data.
10Best Practices and Common Mistakes
Practical guidance for anyone setting up or maintaining an LDAP integration.
Always Encrypt the Connection to the Directory
Never allow directory credentials and data to travel over an unencrypted connection.
Use a Dedicated, Minimally Privileged Bind Account
Avoid reusing a broad administrative account purely out of convenience.
Choose the Sync Mode Deliberately
Decide between read-only, writable, and unsynced based on who should genuinely own changes to user data.
Set a Sensible Sync Schedule
Balance how quickly directory changes should be reflected against the load repeated syncing places on the directory server.
Common missteps include forgetting that disabling a user in the directory doesn’t instantly disable their Keycloak session until the next sync, misconfiguring search filters so some legitimate users are silently excluded, and enabling writable mode without first agreeing on it with the directory’s own administrators.
11Advantages and Disadvantages of LDAP Integration
A fair look at what federating with an existing directory gains you, and what it costs.
Advantages
- Avoids duplicating and maintaining a second, separate copy of user accounts
- Employees keep using the same, already-familiar corporate credentials
- Leverages existing account lifecycle processes, like onboarding and offboarding
- Directory group memberships can map naturally into application permissions
Disadvantages / Trade-offs
- Adds a dependency on the directory server’s own availability and performance
- Sync delays mean directory changes aren’t always reflected instantly
- Requires careful, ongoing coordination with the directory’s own administrators
- Misconfiguration can expose sensitive corporate directory data or credentials
12Monitoring LDAP Integration Health
Because this integration depends on an external system, keeping an eye on it matters.
Sync Success and Failure Logging
Tracking whether scheduled synchronizations complete successfully helps catch connectivity or permission issues early.
Bind Account Activity Monitoring
Watching for unusual activity on the dedicated bind account can reveal misuse or compromise of that credential.
Login Failure Pattern Tracking
A spike in federated login failures may point to directory connectivity problems rather than a genuine wave of incorrect passwords.
13Real-World and Industry Examples
Seeing LDAP integration applied in realistic organizational settings.
Corporate Active Directory Integration
Large organizations very commonly connect Keycloak to their existing Active Directory, letting employees log into every internal web tool with the exact same corporate username and password they already use for their computer and email.
Universities and Research Institutions
Academic institutions often maintain a large, centrally managed directory of students and staff, which Keycloak can federate with so campus systems don’t each require a separate account.
Mergers and Multi-Directory Organizations
A company formed from multiple mergers might configure several separate LDAP integrations, each pointed at a different legacy directory, letting employees from different original organizations continue logging in with their existing accounts during a transition period.
14Frequently Asked Questions
No — with LDAP integration, the user’s existing directory password is what gets checked during login. They continue using the same credentials they already have, without creating a new one specifically for Keycloak.
No — password verification is performed by the directory itself. Keycloak asks the directory to confirm whether submitted credentials are correct, rather than storing and checking passwords locally.
In read-only mode, Keycloak reads user data from the directory but never writes changes back — updates must be made in the directory itself. In writable mode, certain changes made through Keycloak are written back into the connected directory as well.
Not necessarily instantly — due to caching and periodic synchronization, there can be a short delay before that change is reflected inside Keycloak, depending on the configured sync schedule.
Yes — attribute mappers can be configured to translate a user’s existing directory group memberships into corresponding Keycloak groups or roles, letting existing organizational structure drive application access automatically.
Yes — a realm can be configured with multiple separate LDAP integrations simultaneously, which is common during organizational mergers or when different departments maintain their own separate directories.
15Summary and Key Takeaways
LDAP integration lets Keycloak authenticate users directly against an organization’s existing directory — most commonly Active Directory — instead of duplicating those accounts into a second, separate database. By checking credentials against the directory itself, periodically syncing user information, and mapping directory attributes and group memberships into Keycloak’s own fields, this feature lets large organizations extend modern authentication to their applications while keeping their existing directory as the single, authoritative source of truth about who their users actually are.
Key Takeaways
- LDAP integration lets Keycloak authenticate against an existing directory instead of duplicating user accounts.
- Password verification happens at the directory itself, not through a locally stored copy inside Keycloak.
- Three sync modes — read-only, writable, and unsynced — control how changes flow between Keycloak and the directory.
- Periodic synchronization and caching mean directory changes may take a short while to be fully reflected inside Keycloak.
- Attribute mappers translate directory fields — including group memberships — into the fields and roles Keycloak expects.
- A narrowly scoped, encrypted bind connection is essential, since the integration touches a sensitive, often company-wide directory.
- Keeping the directory as the single source of truth, with Keycloak as a consumer of it, avoids two systems drifting out of sync.