What Is User Federation in Keycloak? Connecting to the Directory You Already Have
A beginner-friendly guide to Keycloak's User Federation feature — how it lets you reuse an existing corporate directory instead of duplicating every employee's account, and how it actually works behind the scenes.
Imagine a large company that has kept a single, meticulously maintained employee directory for the last fifteen years — every hire, every department transfer, every resignation carefully recorded in one place. Now imagine that company adopting a brand-new tool for managing logins, and being told the only way to use it is to manually retype every single employee’s details into a second, completely separate list. That would be wasteful, error-prone, and would immediately create two directories that could quietly drift out of sync with each other. Keycloak’s User Federation exists specifically to avoid this problem — it lets Keycloak reach into an existing directory that already exists, and use it directly, rather than forcing a costly, duplicate copy of every user.
1What Is User Federation?
Let’s build a clear, plain-English understanding before looking at how it actually works underneath.
The Simple Definition
User Federation is a Keycloak feature that connects a realm to an external source of user accounts — most commonly a company’s existing LDAP directory or Active Directory — so that those external accounts can be used for login without ever being copied wholesale into Keycloak’s own database. Instead of asking “who does Keycloak know about,” federated setups effectively ask “who does this connected external directory know about,” and trust that answer directly.
Think of a library that partners with a neighboring university’s library system instead of manually photocopying every one of its thousands of books onto its own shelves. When you ask for a specific book, the library quietly checks the university’s catalog in real time and fetches what’s needed, rather than maintaining a separate, ever-growing duplicate collection that could easily fall out of date.
Where the Term Comes From
The word “federation” here describes a relationship between systems that stay independently owned and managed, but cooperate closely — much like a federation of states retains separate local governments while still operating under shared rules. Keycloak doesn’t take ownership of the external directory; it simply federates with it, treating it as a trusted, ongoing source of truth for user identity.
User Federation
Keycloak’s mechanism for connecting to and using an external user directory for login.
LDAP
A widely used, open standard protocol for storing and querying directory information like user accounts.
Active Directory
Microsoft’s popular directory service, commonly used by organizations to manage employee accounts, built on LDAP.
Federation Provider
The specific configuration Keycloak uses to connect to one particular external directory.
User Federation is different from a related feature called Identity Brokering, which lets users log in via an external identity provider like Google by being redirected there. Federation instead connects Keycloak directly to a directory of existing accounts, and Keycloak itself still presents the login screen.
2Why Companies Need This Instead of Just Importing Users
It’s worth understanding exactly what problem federation solves, compared to the simpler-sounding alternative of just copying users over once.
At first glance, importing every user from an existing directory into Keycloak’s own database might sound like a reasonable one-time task. But real organizations aren’t static — employees join, leave, change departments, and reset forgotten passwords constantly. A one-time import creates a snapshot that starts going stale the moment it’s taken, and without an ongoing connection back to the original source, that snapshot has no way of staying accurate.
Problems With a One-Time Copy
- New employees added to the original directory don’t automatically appear in Keycloak
- Departed employees keep their Keycloak access even after being removed elsewhere
- Password changes in the original system aren’t reflected in the imported copy
- Two separate directories can quietly drift apart, creating confusing inconsistencies
What User Federation Provides Instead
- Keycloak checks the live directory directly, rather than a stale, frozen copy
- New hires and departures are reflected automatically, without any manual sync step
- Password changes made in the original directory work immediately for Keycloak logins
- One single source of truth for identity, avoiding duplicated, drifting data
It’s the difference between checking a live flight-status board versus glancing at a printout taken an hour ago. The printout might have been accurate at the time, but only the live board reliably reflects what’s actually true right now — and User Federation is Keycloak’s way of always checking the live board instead of relying on an outdated printout.
3Core Building Blocks of User Federation
Understanding a few core pieces makes the rest of federation easy to follow.
Federation Provider
The connection configuration itself — the address, credentials, and settings Keycloak uses to reach the external directory.
Attribute Mapper
A rule translating a field in the external directory, like an employee ID, into a field Keycloak understands and can use.
Edit Mode
A setting controlling whether changes, like a password reset, can be written back to the external directory, or only read from it.
Synchronization Settings
Optional rules for periodically caching a lightweight local record of federated users, improving performance for large directories.
LDAP: The Most Common Federation Source
The most widely federated source is LDAP (Lightweight Directory Access Protocol), a decades-old, open standard specifically designed for storing and querying hierarchical directory information, such as organizational structures and user accounts. Microsoft’s Active Directory, extremely common in corporate environments, is itself built on LDAP, which is why Keycloak’s LDAP federation provider works with Active Directory as well as other LDAP-compliant systems.
LDAP is a bit like a universal filing cabinet standard used across many different office supply brands. Because so many different directory systems agree on the same basic filing format, a single, standardized way of asking “find me this record” works across many of them, which is exactly what Keycloak’s LDAP federation provider takes advantage of.
User Federation doesn’t require Keycloak to permanently store a full copy of every federated user’s data. Depending on configuration, Keycloak may keep only a minimal, temporary local reference and query the external directory directly for the rest, rather than fully duplicating the entire user record.
4Architecture: How Federation Fits Into a Login
Let’s look at exactly where the federated directory sits in relation to Keycloak’s own login process.
flowchart LR
U[User's Browser] -->|1 Enters Credentials| KC[Keycloak Server]
KC -->|2 Checks Federation Provider| PROV[Federation Provider Config]
PROV -->|3 Queries in Real Time| LDAP[(External LDAP / Active Directory)]
LDAP -->|4 Confirms or Denies Credentials| KC
KC -->|5 Issues Tokens on Success| U
Realm-Level Configuration
Like most identity features in Keycloak, a federation provider is configured per realm, meaning different realms can connect to entirely different external directories, or none at all. This configuration includes the network address of the directory, credentials Keycloak itself uses to query it, and rules for which parts of the directory to search.
Real-Time Directory Queries
When a federated user attempts to log in, Keycloak reaches out to the connected directory directly, checking the submitted username and password against the external system’s own records, rather than relying solely on anything stored inside Keycloak’s own database.
Optional Local Caching
For performance reasons, especially with very large directories, Keycloak can maintain a lightweight local cache of certain user information, periodically refreshed through a configurable synchronization schedule, while still treating the external directory as the ultimate source of truth.
5How a Federated Login Actually Flows
Let’s trace exactly what happens, step by step, when a federated user tries to log in.
User enters their existing corporate username and password
This happens right on Keycloak’s own login page — the user experience looks identical to a normal Keycloak login.
Keycloak checks whether a matching federation provider applies
Based on the realm’s configuration, Keycloak determines this user should be checked against the connected external directory.
Keycloak queries the external directory directly
It sends the submitted credentials to the LDAP or Active Directory system for verification, in real time.
The external directory confirms or denies the credentials
Keycloak receives a straightforward success or failure response from the connected system.
Keycloak proceeds exactly as with any other successful login
Tokens are issued, roles are applied, and the user is redirected back to the application, unaware anything different happened behind the scenes.
From the end user’s perspective, logging in through a federated directory feels completely identical to a native Keycloak login — same page, same fields, same experience. All of the added complexity is handled invisibly behind the scenes.
6Read-Only vs Writable Federation
One important configuration choice determines whether Keycloak can only read from the external directory, or also make changes to it.
Read Only
Keycloak can check credentials and read user details, but cannot make any changes back to the external directory, such as password resets.
Writable
Keycloak can both read from and write changes back to the external directory, such as processing a genuine password reset request.
Unsynced
User data is imported into Keycloak’s own database once, and future changes are made only locally, no longer tied to the external source.
Choosing the right mode depends on how much control an organization wants Keycloak to have over the original directory. Many companies deliberately choose read-only federation, especially for something as sensitive as a corporate Active Directory, preferring that password changes and account management continue to happen through their existing, established internal tools rather than through Keycloak.
Enabling writable federation without fully considering the consequences can unintentionally give Keycloak the ability to modify a sensitive corporate directory that other critical systems also depend on — this setting deserves careful thought, not a quick default choice.
7Mapping Attributes From the External Directory
Directories rarely use the exact same field names Keycloak expects, so a translation step is often necessary.
An external LDAP or Active Directory system might store a user’s department under a field named something like ou or department, while Keycloak’s own concept of a custom attribute might expect a different internal name. Attribute mappers bridge this gap, translating each relevant field from the external directory’s own naming convention into something Keycloak — and by extension, the applications relying on Keycloak — can consistently understand and use for things like role assignment.
It’s similar to a professional interpreter at an international conference. The delegates aren’t required to change how they speak in their own language — the interpreter simply translates each statement into a shared language everyone in the room can understand, without altering the original meaning.
Getting attribute mappings right the first time saves significant troubleshooting later — a surprisingly common source of “the user can log in but has no permissions” issues traces back to a missing or misconfigured attribute mapper rather than anything wrong with the login itself.
8Advantages, Disadvantages, and Trade-offs
Federating an existing directory brings clear benefits, along with a few important trade-offs to weigh.
Advantages
- Avoids duplicating and maintaining a second, separate copy of every user record
- New hires, departures, and changes stay automatically accurate without manual sync work
- Employees keep using the exact same corporate credentials they already know
- Reduces the overall attack surface by keeping one single, well-understood source of truth
Disadvantages / Trade-offs
- Login now depends on the external directory’s own availability and performance
- Misconfigured connections or attribute mappers can cause confusing login or permission issues
- Writable federation adds real operational risk if not carefully controlled
- Requires ongoing coordination between the Keycloak team and whoever owns the external directory
For organizations with an existing, well-maintained directory, these trade-offs are almost always worth it — the alternative of manually managing a second, duplicate set of user accounts tends to create far more ongoing operational risk over time.
9Security Considerations for User Federation
Because federation connects Keycloak to a sensitive external system, a few security considerations deserve particular attention.
Encrypted Connections
The connection between Keycloak and the external directory should be encrypted, protecting credentials in transit during every login.
Least-Privilege Service Account
The credentials Keycloak itself uses to query the directory should have only the minimum permissions needed, not broad administrative access.
Careful Edit Mode Selection
Read-only federation limits Keycloak’s ability to affect the external directory, an important consideration for especially sensitive systems.
Directory Availability Planning
Since login now depends on the external directory, its own uptime and redundancy become just as important as Keycloak’s.
10Monitoring, Logging, and Metrics
Because federation adds an external dependency to the login process, ongoing visibility into its health matters a great deal.
| What to Monitor | Why It Matters |
|---|---|
| Federation provider connection failures | An unreachable directory can block logins for every federated user at once |
| Query response latency | A slow external directory directly translates into slow, frustrating logins |
| Failed login rate for federated users | Spikes may indicate a directory-side issue rather than a Keycloak problem |
| Synchronization job success rate | Failed periodic syncs can leave cached local data increasingly out of date |
Because a federation failure can quietly lock out an entire population of users at once, many teams set up dedicated alerts specifically for federation provider connectivity, treating it as a critical dependency rather than a background detail.
When federated logins suddenly fail across the board, checking the external directory’s own health and network reachability is often a faster path to diagnosis than assuming the problem lies within Keycloak’s own configuration.
11Design Patterns and Anti-Patterns
Real-world experience running federated Keycloak deployments has surfaced clear, practical guidance.
Pattern: Prefer Read-Only Federation for Corporate Directories
Keeping password management in the organization’s existing, established tools while using Keycloak strictly for authentication reduces operational risk and confusion.
Pattern: Use a Dedicated, Limited Service Account
Query the external directory using a narrowly scoped account created specifically for Keycloak, rather than reusing broad administrative credentials.
Pattern: Test Attribute Mappings Thoroughly Before Rollout
Verify that every important field — department, group membership, email — maps correctly before federated users start relying on the connection for daily logins.
Problem
Configuring Keycloak’s federation service account with full administrative rights over the entire corporate directory, purely for convenience during initial setup.
Why It’s Harmful
If Keycloak’s own credentials or configuration are ever compromised, an attacker could gain far broader access to the corporate directory than federation actually requires.
Correct Approach
Grant only the narrow, read-focused permissions federation genuinely needs, following the principle of least privilege even during initial setup.
Problem
Skipping any monitoring or alerting on the federation provider’s connectivity, treating it as a “set it and forget it” configuration.
Why It’s Harmful
Since federation is often a hard dependency for a large population of users, an unnoticed outage can silently lock out many people at once, with no early warning before support tickets start flooding in.
Correct Approach
Set up dedicated monitoring and alerting specifically for federation provider health, treating it with the same seriousness as any other critical infrastructure dependency.
12Best Practices and Common Mistakes
Concrete, practical habits for a smooth, reliable federation setup.
Encrypt the Connection End to End
Always configure the connection between Keycloak and the external directory to use encryption, protecting credentials as they travel between systems.
Document Attribute Mappings Clearly
Keep a clear internal record of exactly how each external field maps to its Keycloak equivalent, helping future troubleshooting go faster.
Coordinate With the Directory’s Own Owners
Establish clear communication with whoever manages the external directory, since changes on their side can directly affect Keycloak logins.
Plan for Directory Downtime
Understand and communicate clearly what happens to logins if the external directory becomes temporarily unreachable.
Assuming federation setup is a one-time task that never needs revisiting. Organizational directories change structure over time — new organizational units, renamed fields, restructured groups — and federation configuration should be periodically reviewed to ensure it still matches reality.
13Real-World and Industry Examples
User Federation shows up constantly wherever an organization already has an established directory it doesn’t want to abandon.
Large Enterprises With Active Directory
Companies that have relied on Active Directory for years commonly federate it with Keycloak, letting employees use their exact existing corporate credentials across newly adopted modern applications.
Universities and Research Institutions
Academic institutions with large, centrally managed LDAP directories of students and staff frequently federate them, avoiding the need to separately manage credentials for every connected academic tool.
Government Agencies
Public sector organizations with strict identity governance requirements often federate existing, carefully controlled directories rather than introducing a second, separately managed set of accounts.
Companies Mid-Migration to Modern Tooling
Organizations transitioning gradually from legacy systems to modern applications use federation as a bridge, letting them adopt Keycloak-based Single Sign-On without a disruptive, all-at-once identity migration.
Whenever an organization already trusts an existing directory and wants to avoid the cost and risk of duplicating it, User Federation is very often the feature that bridges that gap.
14Frequently Asked Questions
Not necessarily in full — depending on configuration, Keycloak may keep only a lightweight local reference while checking credentials against the live external directory in real time.
No. Federation connects Keycloak directly to a directory of existing accounts, while Identity Brokering redirects users to log in at a separate external identity provider, like Google, entirely outside Keycloak’s own login page.
Yes, if the federation provider is configured in writable mode, allowing Keycloak to write changes, like a new password, back to the external directory.
Federated users typically cannot log in until the connection is restored, since their credentials are checked against that live external system rather than stored independently inside Keycloak.
Keycloak’s built-in federation support centers on LDAP-compatible systems, though custom federation providers can be developed for other kinds of external user stores if needed.
Yes, Keycloak supports configuring multiple federation providers within a single realm, useful for organizations with more than one existing directory to connect.
15Summary and Key Takeaways
User Federation lets Keycloak connect directly to an organization’s existing directory — most commonly LDAP or Active Directory — rather than forcing a costly, ever-drifting duplicate copy of every user account. By checking credentials against the live external system in real time, federation ensures new hires, departures, and password changes stay accurate automatically, without manual synchronization work. Choosing the right edit mode, mapping attributes carefully, and monitoring the connection’s health are all essential to making federation a smooth, reliable bridge between Keycloak and the directory an organization already trusts.
Key Takeaways
- User Federation connects Keycloak to an existing directory, avoiding a costly, drifting duplicate copy of every user.
- LDAP and Active Directory are the most common federation sources, checked in real time during login.
- Edit mode controls whether Keycloak can only read, or also write changes back to the external directory.
- Attribute mappers translate external directory fields into something Keycloak and connected applications can consistently use.
- Login now depends on the external directory’s own availability, making its uptime and performance an important shared concern.
- Federation is different from Identity Brokering — one connects to a directory directly, the other redirects to an external identity provider.
- Least-privilege service accounts and encrypted connections are essential security practices for any federation setup.