Keycloak user federation or identity brokering: which fits your estate
Start with user federation if your LDAP or Active Directory directory is the source of truth for passwords, accounts and group membership, and Keycloak only needs to read them. Start with identity brokering if an external OIDC or SAML provider already authenticates your users and owns multi-factor authentication, and Keycloak should accept that login rather than hold credentials. Most estates are decided by one question: who the team expects to change a password, enroll a second factor or disable a leaver. Federation fits when the directory owns the password. Keycloak connects through its LDAP user federation provider, reads users and groups, and validates credentials against the directory on login. Keycloak can then issue OpenID Connect or SAML tokens to applications without copying passwords into its own database. Confirm with the directory team which attributes are writable from Keycloak, how group membership maps to roles, and whether the bind account has read access limited to the required search base. MFA usually stays with the directory or a separate step you configure in Keycloak, so verify that before you promise a second factor to application owners.
Brokering fits when an external identity provider, such as a corporate OIDC or SAML service, authenticates users and owns MFA and device policy. Keycloak redirects the user to that provider through an identity provider configuration, receives the assertion or token, and maps claims to local users and roles. The external provider stays the system of record for credentials, so Keycloak does not need a directory bind account. Check which claims or attributes the upstream provider sends, because mapper configuration in Keycloak depends on them, and decide whether first-login account creation or a pre-provisioning process will create the local user. The two patterns are not exclusive. One realm can federate a directory for some user populations and broker a partner or cloud provider for others, and the choice does not change with Keycloak's Apache-2.0 license or with the current 26.8.1 release. Test both paths in a non-production realm with real group mappings before you commit, and record which system owns each lifecycle step: password reset, MFA enrollment, group changes and account disablement.
How federation and brokering differ for passwords, MFA and provisioning
With LDAP or Active Directory user federation, Keycloak reads users from the directory and remains the service where login happens. By default, the password is validated against the directory, and Keycloak does not keep its own copy of that password. Keycloak's authentication flows then run on top of that step, so any second factor that Keycloak enrolls is enforced by Keycloak, not by the directory.
- Password check: Keycloak sends the user's credentials to the directory for validation, so the directory stays the authority for the password itself.
- Keycloak MFA: OTP or WebAuthn credentials enrolled in Keycloak are stored in Keycloak's database and required by the browser flow after the password step.
- Directory-side MFA: A second factor enforced by the directory or a separate smart card service is invisible to Keycloak unless you integrate it into the flow.
- Password changes: Whether a password change made through Keycloak is written back to the directory depends on the provider's update settings.
Confirm which authentication flow your realm uses, whether OTP or WebAuthn is required for federated users, and whether password changes are written back to the directory in your version.
Federation creates or refreshes Keycloak user records from the directory, so Keycloak holds a local representation of each federated user even though the directory owns the identity. The import mode, sync schedule and attribute mappings are set in the LDAP provider configuration. The Keycloak server administration guide describes these options, and the behaviour when someone leaves depends on how they are set, so they need testing before go-live.
- Import mode: The provider decides which attributes are copied into Keycloak's database and how often the directory is queried on demand.
- Sync schedule: Periodic full and changed-user syncs bring new and updated accounts into Keycloak. Ask for the interval in writing as part of the design.
- Attribute mapping: Mapping directory attributes to Keycloak user fields and roles determines which claims applications receive.
- Disabled or removed accounts: Keycloak's local record changes on the next sync or login attempt, so there can be a delay between the directory change and the Keycloak change.
Test a disabled account and an account moved out of the search scope, then confirm when existing Keycloak sessions and tokens end in your version.
With brokering, Keycloak redirects the user to an external OpenID Connect or SAML identity provider and accepts the token or assertion that comes back. The password is checked at the external provider, and Keycloak does not receive it. MFA is enforced by that provider, so the strength of the second factor depends on what the upstream requires and what it reports back to Keycloak.
- Password location: The external provider holds the credential, and Keycloak keeps only the link between the external identity and a local account.
- Upstream MFA visibility: Keycloak can read the authentication context the upstream includes in its response, but any decision based on it is a configuration choice. Confirm what your upstream sends.
- Local MFA after brokering: You can require Keycloak's own second factor after a brokered login, which adds a step the upstream did not enforce. Confirm how it stacks with the upstream prompt.
- Trust configuration: Issuer, endpoints and signing keys are trust decisions. A compromised upstream affects every brokered login, so document who administers that trust.
Test a brokered login with upstream MFA required and with it not required, and confirm what Keycloak records in its events and tokens.
On the first brokered login, Keycloak can create a local user from the claims it receives, typically through a first broker login flow that you configure. Later logins can refresh that record. Whether Keycloak removes or disables local accounts when the upstream account stops working is a configuration and version question, so the removal path needs to be designed on purpose. Without one, the local account can outlive the person.
- Account linking: The first-login flow decides whether a new local account is created or an existing one is linked. Matching on a mutable attribute such as email needs careful review.
- Attribute updates: Claims refresh the local profile only when the user signs in again, so changes in the upstream reach Keycloak at the next login.
- Session end: Ending the upstream session does not automatically end Keycloak sessions. Confirm whether logout propagation is available and configured in your version.
- Deprovisioning: Disabling the upstream account blocks new brokered logins, but existing Keycloak sessions and local accounts need an explicit process. If you need automatic removal, confirm what your version and provisioning tooling support.
Test a leaver end to end, from upstream disablement through Keycloak session and token expiry, and record how long each step takes in your environment.
Federation vs brokering side by side
This table compares LDAP or Active Directory user federation with brokering logins to an external OpenID Connect or SAML 2.0 provider, row by row for the decisions that matter most. Read each row as a question to ask your directory or identity team, and treat the cells as the default behavior of each pattern rather than a complete design. The main takeaway is that federation moves the password check and user lookup to your directory, while brokering moves them to the external provider.
| Decision factor | User federation (LDAP or Active Directory) | Identity brokering (external OIDC or SAML 2.0) |
|---|---|---|
| Source of truth | The directory holds the user record, and Keycloak reads it and can cache imported attributes locally. | The external identity provider holds the user record, and Keycloak stores only the links and attributes it receives at login. |
| Where passwords are verified | Keycloak sends the bind request to the LDAP or Active Directory server, so the password is checked against the directory. | The external provider authenticates the user, and Keycloak receives a signed token or assertion and never checks the password itself. |
| MFA ownership | MFA is enforced by Keycloak or a second factor it manages, since the directory typically holds only the password. | MFA is usually enforced by the external provider, so confirm what it asserts before relying on it in Keycloak policy. |
| User provisioning and attribute sync | Users are imported or looked up on demand, and attribute mappers control which directory fields are copied. | Users are created on first login by default, and attributes arrive only when the external provider sends them. |
| Group and role mapping | Directory groups map to Keycloak groups and roles through mappers, and changes flow in on sync. | Claims or SAML attributes map to roles at login, so group changes apply the next time the user signs in. |
| Dependency on directory or external IdP | Logins fail if the directory is unreachable, and cached users may still exist without a live password check. | Logins fail if the external provider is unreachable, and existing Keycloak sessions depend on that provider only at sign-in. |
| Operational effort | Keycloak needs directory service accounts, TLS to the directory and sync schedules to maintain. | Keycloak needs trust settings, client registration and metadata or certificate rotation for each external provider. |
| Cost of switching later | Moving off the directory means migrating user records and password handling, which is a larger change. | Replacing the external provider means updating trust and mappers, while local user records may remain in Keycloak. |
What Active Directory and Entra ID change for federation
The first question is who owns the directory. Microsoft describes Active Directory Domain Services as the directory that stores users, computers and other objects, and it notes that most on-premises applications authenticate against it through LDAP, Windows-integrated authentication (NTLM and Kerberos) or header-based authentication. Keycloak can read that directory directly through its LDAP or Active Directory user federation, which keeps passwords in Active Directory and lets Keycloak issue OIDC or SAML tokens to applications. Microsoft also says that SaaS applications need a federation system such as AD FS to reach Active Directory, so a Keycloak deployment that serves browser-based apps is one of the places where that gap is filled. Confirm which applications use LDAP binds, which use Kerberos, and which only accept SAML or OIDC before you pick a route.
If your organization already syncs identities to Microsoft Entra ID with Microsoft Entra Connect, the upstream provider may already own sign-in, MFA and conditional access. In that case, brokering Keycloak to Entra ID as an external OIDC or SAML identity provider can be the simpler path, because Keycloak then trusts the cloud tenant rather than binding to domain controllers. Federating directly to Active Directory instead means Keycloak carries the directory dependency and must be sized and secured for those LDAP connections. Decide where MFA policy, password resets and account lockout should live, and write that decision down, because the answer changes which of the two Keycloak mechanisms you configure.
Linux hosts need separate planning. Microsoft's comparison notes that Linux machines need third-party tools or must be configured to authenticate against Active Directory as a Kerberos realm, and Keycloak does not join servers to a domain. If your estate includes Linux servers that must accept Active Directory accounts, plan that work outside Keycloak, and confirm whether a FreeIPA trust or another tool covers it. Keycloak federation or brokering solves browser and API sign-in, not host login.
How to combine federation and brokering in one realm
This sequence sets one authoritative source for each user and each login path before any connection goes live, so Keycloak can read the directory, broker partner logins and resolve conflicts in a predictable order. The result is a documented realm configuration that your team has tested with real accounts in your own environment.
Decide which system owns passwords and MFA
Your identity owner, security lead and directory administrator agree, in writing, which system stores credentials and enforces multi-factor authentication for each user group. Typical choices are the on-premises directory for workforce passwords, Keycloak for MFA, or the external provider for partner accounts. Keycloak's LDAP and Active Directory federation reads the directory, so any password check against the directory stays there. Done when every user group has a named owner for passwords and a named owner for MFA, and the decision record is signed off.
Connect the directory as a user federation provider
The directory administrator creates a read-only service account with the minimum attributes Keycloak needs, and the Keycloak administrator configures an LDAP or Active Directory user federation provider in the target realm. Confirm the bind method, TLS settings, and which attributes Keycloak imports or reads on each login with the vendor documentation and your directory team, because these settings depend on your directory version and policy. Done when a test user from the directory can authenticate and the imported user record shows the expected username, email and group membership.
Add brokered identity providers for partners and cloud identity
For each external OpenID Connect or SAML identity provider, the realm administrator adds an identity provider entry, registers Keycloak as a client on the partner side, and exchanges metadata or client details through a channel your security team approves. Keep each brokered provider on its own alias so that its login path is distinct from the directory path. Done when a test user from the partner completes a brokered login, and Keycloak shows the expected identity provider link on the user record.
Map attributes and groups from each source
The realm administrator defines attribute and group mappers for the federation provider and for each brokered provider, so that every source fills the same set of user attributes and roles used by your applications. Document which source is the master for each attribute, such as department from the directory and partner organization from the brokered provider. Done when a test user from each source receives identical claim names in the token, and the mapping document lists the source for every claim.
Set the rule for conflicts between sources
When the same person can appear through the directory and a brokered provider, or when two sources return different values for one attribute, the identity owner writes an explicit rule. Specify whether Keycloak links accounts automatically by a trusted claim, requires a user to confirm the link, or blocks the login and sends the user to an administrator. Test each rule with a deliberately conflicting account in a non-production realm. Done when the rule is written, each conflict case has a recorded test result, and the security lead has approved the rule.
Test every login path and the fallback
The test lead runs a scripted set of logins: directory password with MFA, each brokered provider, a disabled directory account, a directory outage, and a user who exists in two sources. Record which path each login takes and whether the fallback behaves as designed, such as a local emergency administrator account that is kept off the normal paths. Repeat the tests after any change to the realm, the directory or a partner configuration. Done when every path has a dated pass or fail result and each failure has an owner and a fix.
Document the order in which sources are consulted
The Keycloak administrator and identity owner write down the sequence Keycloak follows for each login, including which identity provider the login screen offers first, when the federation provider is queried, and how the link and conflict rules apply. Store the document with the realm configuration export and assign a reviewer for each change. Confirm the exact behavior against the Keycloak version you run, because login flow details can change between releases. Done when the order is in the change record, the reviewer has signed it, and the team can explain the sequence to an auditor without reading the admin console.
Decision points before you pick a pattern
Each question below changes which pattern fits, so answer them before you open a design review. Federation and brokering make different promises about where passwords, MFA, accounts and group data live, and those promises are usually set by the directory or identity owner rather than by Keycloak.
Where passwords must stay
If policy requires that passwords never leave the directory, LDAP or Active Directory federation fits because Keycloak validates credentials against the directory at login. Brokering sends the user to an external OIDC or SAML provider, so the external provider authenticates the user and Keycloak receives a token. Confirm with the directory owner whether password hashes or bind operations are permitted, and whether Keycloak may cache any credential data.
Where MFA is enforced
If MFA must be enforced by the directory or the external identity provider, Keycloak should trust that result and not add a second factor of its own. If Keycloak must enforce MFA for every application, you need to configure it in Keycloak, which applies to federated users only where your authentication flows say so. Confirm with the security owner which factor store is authoritative, how enrollment works, and what happens when a user has no enrolled factor.
Whether accounts must exist first
Federation can import users into Keycloak on first login or keep them read-only in the directory, so you decide whether a local Keycloak record must exist before sign-in. Brokering often creates a local user on first login, and attributes sent by the external provider decide what that record holds. Check with the identity owner whether deprovisioning must remove access in Keycloak immediately, and how disabled accounts are detected in each design.
Whether external partners need access
Brokering suits partners, contractors and customers who already have an identity in their own OIDC or SAML provider, because Keycloak does not need their accounts in your directory. Federation assumes users belong to a directory you operate, which rarely covers outside parties. Confirm with the partner program owner which external providers must be trusted, which claims they send, and who signs off on each trust relationship.
Whether the directory is reachable
LDAP federation requires a live network path from the Keycloak network zone to the domain controllers or LDAP servers, including the ports and TLS settings your directory team approves. If the directory sits in a separate zone that cannot accept inbound connections from Keycloak, brokering to an identity provider that is already reachable from your edge may be the simpler route. Confirm firewall rules, service account scope and the LDAPS certificate chain with the network and directory teams before you build.
Whether groups drive authorization
If access decisions depend on directory group membership, you must confirm that group data reaches Keycloak through federation mappers or through claims sent by the external provider. Missing or renamed groups will silently change what users can reach, so test with a sample of real accounts. Ask the directory owner which group types are in scope, how nested groups are resolved, and how often membership changes must take effect.
Operating federation and brokering after go-live
The ongoing cost of this design sits in the connections, not the initial setup. Each LDAP or Active Directory federation link and each brokered OIDC or SAML provider is a dependency that can break silently. Monitor the federation provider status and sync results in the admin console, and track login failures per identity provider alias. Keycloak exposes metrics that you can scrape, so confirm which ones your platform team will alert on, and test what happens when the directory is unreachable: whether cached federated users can still sign in, and whether brokered logins fail cleanly. Confirm these behaviors in your own environment, because they depend on your sync settings and directory topology.
Certificate and metadata rotation is where brokering most often causes outages. SAML signing certificates, OIDC client secrets and upstream signing keys all expire on their own schedules, and the external provider may rotate them without notice to you. Assign an owner for each brokered provider, record its expiry date, and schedule a rotation test in a non-production realm before the change reaches production. For upgrades, the project plans four minor releases a year and states that breaking changes in a minor release will be opt-in, so read each release note and migration guide before applying it. If you run the Operator, the Operator documentation strongly recommends manual approval mode so that an operator update does not upgrade Keycloak unattended.
Production databases and login testing close the loop. Keycloak needs a relational database in production, and neither the Keycloak Operator nor the server distribution provisions or operates it for you. Your team or a database provider owns backups, patching, failover and the synchronous replication that Keycloak's high availability designs require, so ask who holds those duties before go-live. Keep a written list of login paths (each federated directory, each brokered provider, SAML and OIDC clients, and any administrator login) and run them after every configuration change, certificate rotation or upgrade. Schema migration runs automatically at startup by default, so decide in advance whether large upgrades should use manual migration, as the Keycloak upgrading guide describes.
Questions buyers ask about federation and brokering
Can Keycloak read Active Directory directly without a middle layer?
Yes. Keycloak supports user federation from LDAP or Active Directory, so it reads users and their attributes from the directory and serves them to applications through its own sessions and tokens. The directory stays the source of truth for accounts and group membership, while Keycloak handles protocols such as OpenID Connect and SAML. Confirm the exact bind method, which attributes sync on import or on demand, and how disabled accounts are treated, using the Keycloak server administration guide and a test realm that mirrors your directory layout before you commit to a design. Ask your identity team which service account Keycloak will use, what read rights it needs, and whether LDAPS will be required on the connection.
Does brokering remove the need for a directory?
No. Brokering moves the login to an external OpenID Connect or SAML identity provider, but that provider still needs a source of accounts. Often that source is Active Directory, reached through a federation service, or a cloud identity service that synchronizes from an on-premises directory. Microsoft notes that on-premises Active Directory needs a federation system such as AD FS for SaaS apps, and that existing organizations use Microsoft Entra Connect to sync identities to Entra ID, as described in the Active Directory and Entra ID comparison. Brokering changes where the password check and lifecycle work happen. Confirm which system is the authoritative source for joiners, movers and leavers before you choose brokering.
How is MFA handled in federation and in brokering?
The two paths place MFA in different systems. With LDAP or Active Directory federation, Keycloak checks the password against the directory, so you configure second factors inside Keycloak's authentication flows for the realm. With brokering, the external provider authenticates the user, and Keycloak accepts the assertion it receives. In that case the MFA decision sits upstream, so Keycloak can only enforce what the provider reports. Confirm three things before design: which second factors each system supports, what authentication context the upstream provider sends back, and whether any application needs a step-up check that Keycloak must enforce itself. Keep the answer in your written design, because auditors will ask where the control runs.
What drives the effort to implement each pattern?
Effort follows the number of directories, the attribute and group mappings, the protocols each application uses, and the production database. Federation adds work on the directory side: attribute mapping, group-to-role decisions, and testing how password changes and account lock states reach Keycloak. Brokering adds work per upstream provider: client registration, metadata exchange, claim mapping and certificate handling for SAML. Both need a production database, because Keycloak requires a relational database in production and the dev-file database is not suitable for it, as the database guide explains. Windows Server licensing is a separate cost if Active Directory is the source, since Microsoft prices it per core with a 16-core minimum per server and requires client access licenses. Ask for each of these as separate lines in any quote.
What does the implementation need from our identity and network teams?
The identity team supplies the directory design, a dedicated read-only service account, the group structure that maps to roles, and the owner of each attribute that Keycloak will read or write. They also decide which upstream identity providers are approved and who signs off on certificate and metadata changes. The network team needs firewall paths from the Keycloak nodes to the chosen domain controllers or the upstream provider endpoints, plus DNS and certificate trust for LDAPS or SAML metadata. Ask both teams to confirm change windows, logging requirements and break-glass access before the work starts. Those dependencies usually set the schedule more than the Keycloak configuration itself, so list them in the written scope with named owners.
Can our in-house team implement this without outside help?
A capable team can, if it already runs directories, Keycloak or another IdP, and a production relational database. The skill gaps usually sit in LDAP query tuning, certificate trust, SAML signing, and upgrade planning. Keycloak's own operator documentation strongly recommends manual approval mode for operator updates to avoid unintended automatic upgrades, so someone must own that process. If skills are thin, DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, typically under a fixed scope agreed in writing. Ongoing support, upgrades and testing are available as retainers. Compare your team's current skills against the list above before deciding which parts to keep in-house.
How long does each pattern take to implement?
This page does not give a duration, because the time depends on the directory size, the number of applications and upstream providers, and how many identity and network approvals are needed. The written scope sets the timeline for each engagement, and it lists the deliverables and the dependencies on your teams. Ask for the timeline to show separate phases: design, a test realm, production cutover, and handover. Also ask how the plan handles an upgrade after go-live, because Keycloak's minor releases are planned four times a year and its breaking changes are opt-in, according to the Keycloak release updates post. Request a timeline that names the assumptions behind each phase.
How DeployOpen scopes and delivers Keycloak federation and brokering
DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, so Keycloak runs in your cloud account, data center or air-gapped network. We start by agreeing on which identities stay in your directory, which move to an external provider and which logins need MFA, then build and document that design in writing.
How we scope
- Engagements are fixed-scope, with the federation, brokering and mixed design agreed in writing before work starts.
- The written scope lists which LDAP or Active Directory attributes Keycloak reads and which external OIDC or SAML providers it trusts.
- Scope also records where credentials and MFA are enforced, which determines whether a directory or an upstream provider is the source of truth.
How we build
- We configure user federation or identity brokering in a test realm, then test login, password change, lockout and group mapping for each path.
- We set up the production database, the chosen high availability design and the deployment method your platform team already runs.
- We document each mapper, claim and provider trust so your team can review the configuration without reverse engineering it.
How we hand over
- Handover covers runbooks for adding an identity provider, rotating bind credentials and recovering from a failed directory sync.
- Your team receives configuration exports, a test record for each login path and a list of open decisions for the next review.
- We confirm with you which provisioning steps stay manual and which, if any, need a separate governance tool before go-live.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the original build.
- Upgrades are planned against Keycloak's release cadence, and we agree on how schema migration runs in your environment before applying it.
- Quotes follow from the written scope, so ask us to itemize setup, testing, handover and any retainer separately.
