Keycloak User Federation vs Identity Brokering: LDAP/AD vs External IdP

Keycloak can reach users that live outside the realm in two different ways. With user federation, Keycloak talks directly to a user store such as LDAP or Active Directory. With identity brokering, Keycloak sends the browser to another identity provider such as Entra ID, Okta, Google, or another Keycloak realm.

Ask one question to tell them apart: does Keycloak check credentials against a user store, or does another IdP authenticate the user?

Keycloak User Federation vs Identity Provider: Quick Answer

In Keycloak, an external Identity Provider entry is the identity-brokering model. The Admin Console menu is Identity providers. The docs call the same idea identity brokering.

User store vs identity provider

A user store holds accounts, attributes, groups, and credentials. LDAP and Active Directory are common examples.

An identity provider (IdP) runs an authentication flow and tells another system that the user signed in successfully. OIDC and SAML are the usual protocols for that trust. Keycloak 26.x also supports a generic OAuth 2.0 identity provider and built-in social providers. See IdP vs service provider if those roles are new.

In short:

• User federation = Keycloak reads users from an external user store such as LDAP/AD; other stores need a custom User Storage provider.
• Identity brokering = Keycloak sends the user to another IdP, then issues Keycloak’s own tokens to your apps.

Think of federation as storage integration and brokering as authentication trust. Federation lets Keycloak query an external user store and validate credentials there. Brokering lets Keycloak trust a login that already happened somewhere else. Either way, your apps still see a Keycloak user and Keycloak-issued tokens.

How Keycloak User Federation Works

User federation connects Keycloak to an existing user directory. With LDAP or Active Directory, the directory keeps the accounts and passwords. Keycloak uses those users for login, roles, groups, and application access. For other stores, you can implement Keycloak’s User Storage SPI.

At login time, your applications still land on Keycloak’s login page. Behind that page, Keycloak looks up the user through the configured user storage providers (by configuration and priority), maps directory attributes into Keycloak’s user model, and validates credentials against the directory when the provider is set up that way.

For the LDAP/AD provider:

• With Import Users enabled, Keycloak stores LDAP users in its local database when they are first encountered through login or lookup. Synchronization can also import users in bulk. LDAP passwords are never imported.
• Password checks go to LDAP/AD.
• You can sync imported users on demand or on a schedule when import is enabled.
• LDAP mappers control how attributes, groups, and roles map into Keycloak.

The sequence below is a typical browser login when Keycloak validates against LDAP or Active Directory. The browser never opens the LDAP admin UI; the directory check stays between Keycloak and LDAP/AD.

  Browser             Application              Keycloak                 LDAP / AD
     │                     │                       │                        │
     │ 1. Open app         │                       │                        │
     ├────────────────────►│                       │                        │
     │                     │                       │                        │
     │◄────────────────────┤                       │                        │
     │ 2. Redirect to Keycloak                     │                        │
     │                                             │                        │
     ├────────────────────────────────────────────►│                        │
     │                                             │                        │
     │◄────────────────────────────────────────────┤                        │
     │ 3. Login page                               │                        │
     │                                             │                        │
     │ 4. Submit username/password                 │                        │
     ├────────────────────────────────────────────►│                        │
     │                                             │ 5. Find user /         │
     │                                             │    validate password   │
     │                                             ├───────────────────────►│
     │                                             │◄───────────────────────┤
     │                                             │                        │
     │◄────────────────────────────────────────────┤                        │
     │ 6. SAML response or OIDC code               │                        │
     │                                             │                        │
     ├────────────────────►│                       │                        │
     │ 7. Protocol response/code                   │                        │
     │                     │                       │                        │
     │◄────────────────────┤                       │                        │
     │ Authenticated app   │                       │                        │

What happens in this flow:

• Step 1: The browser opens a protected page or starts sign-in in the application.
• Step 2: The application tells the browser to redirect to Keycloak. The application does not call Keycloak as a direct server-to-server login hop here.
• Step 3: The browser requests Keycloak and receives the realm login page.
• Step 4: The user submits username and password to Keycloak. The browser stays on Keycloak for that form.
• Step 5: Keycloak locates the user through the configured LDAP/AD storage provider and validates the password against the directory. LDAP bind is the LDAP operation commonly used for that check. Passwords are not copied into Keycloak’s database.
• Step 6: Keycloak completes authentication and returns the configured SAML or OIDC result through the browser (for example a SAML Response or an OIDC authorization code).
• Step 7: The browser delivers that protocol response or code to the application, and the application completes its own login or session. For OIDC Authorization Code, the client may then exchange the code for tokens. The app trusts Keycloak, not LDAP directly.

What is Keycloak? covers the wider product picture if you want it.

How Keycloak Identity Providers and Identity Brokering Work

Identity brokering hands authentication to another identity provider, often called the upstream IdP. You add that IdP under Identity providers in the Admin Console. Keycloak becomes a broker: your apps still trust Keycloak, and Keycloak trusts Entra ID, Okta, Google, another Keycloak realm, or another IdP you configure over OIDC, SAML, OAuth 2.0, or a social provider.

The login page can show buttons such as “Sign in with Microsoft,” or you can set a default IdP so the browser goes there immediately. After the external IdP authenticates the user, Keycloak validates the returned response and resolves it to a Keycloak user. On a first brokered login with no linked account yet, the configured First Login Flow can create or link that account. The app never has to speak the upstream protocol.

The first brokered login usually creates or links the local account. On later logins, whether IdP attributes update that local user depends on Sync Mode and identity provider mappers. That is login-time synchronization, not a background directory sync.

The sequence below is a typical brokered login. The chain is browser → Keycloak → browser → upstream IdP → browser → Keycloak → browser → application.

  Browser          Application          Keycloak              Upstream IdP
     │                 │                   │                       │
     │ 1. Open app     │                   │                       │
     ├────────────────►│                   │                       │
     │                 │                   │                       │
     │◄────────────────┤                   │                       │
     │ 2. Redirect to Keycloak             │                       │
     │                                     │                       │
     ├────────────────────────────────────►│                       │
     │                                     │                       │
     │◄────────────────────────────────────┤                       │
     │ 3. Login page / IdP redirect        │                       │
     │                                     │                       │
     ├────────────────────────────────────────────────────────────►│
     │ 4. Follow redirect to upstream IdP                          │
     │                                                             │
     │◄────────────────────────────────────────────────────────────┤
     │ 5. IdP login page                                           │
     │                                                             │
     │ 6. Authenticate                                             │
     ├────────────────────────────────────────────────────────────►│
     │                                                             │
     │◄────────────────────────────────────────────────────────────┤
     │ 7. Redirect / response toward Keycloak                      │
     │                                                             │
     ├────────────────────────────────────►│                       │
     │ 8. IdP response                     │                       │
     │                                     │                       │
     │                                     │ Validate response,    │
     │                                     │ resolve/link user,    │
     │                                     │ create KC session     │
     │                                     │                       │
     │◄────────────────────────────────────┤                       │
     │ 9. Redirect / app protocol result   │                       │
     │                                     │                       │
     ├────────────────►│                   │                       │
     │                 │                   │                       │
     │◄────────────────┤                   │                       │
     │ Authenticated app                   │                       │

What happens in this flow:

• Step 1: The browser opens the application.
• Step 2: The application tells the browser to redirect to Keycloak.
• Step 3: The browser reaches Keycloak. Keycloak shows its login page or immediately issues a redirect toward the configured Identity Provider.
• Step 4: The browser follows that redirect to the upstream IdP (for example Entra ID, Okta, or Google).
• Step 5: The upstream IdP presents its own login page.
• Step 6: The user authenticates at the upstream IdP (password, MFA, passkey, or whatever that IdP requires). Keycloak does not see those credentials.
• Step 7: After successful authentication, the upstream IdP redirects the browser back to Keycloak with the protocol response. For OIDC this is typically an authorization code; for SAML it is typically a SAML Response carried through the browser. OAuth 2.0 and social providers each return their own broker response. For OIDC Authorization Code, Keycloak may then exchange the code at the IdP token endpoint.
• Step 8: The browser delivers that IdP response to Keycloak. Keycloak validates it and resolves it to a Keycloak user. On the first brokered login, the configured First Login Flow may create or link the account. For an already-linked identity, Keycloak normally uses the existing account without running that first-login flow again, then creates its SSO session.
• Step 9: Keycloak redirects the browser back to the application with the application’s configured protocol result. The application completes its own login or session.

Your applications see Keycloak as their identity provider. Toward the upstream IdP, Keycloak is the client of that provider: an OIDC Relying Party (RP) or a SAML Service Provider (SP). OAuth vs OIDC vs SAML covers how to pick the protocol on that hop.

Architecture and Login-Flow Differences

The main difference is where authentication happens.

• Federation: Keycloak runs the login flow and validates against the external store.
• Brokering: the external IdP authenticates the user, and Keycloak trusts that result.

The two sketches below compress the earlier sequences into a side-by-side architecture view. Read the top path as federation and the bottom path as brokering.

  Federation path (Keycloak validates against external directory)
  ───────────────────────────────────────────────────────────────
  Browser ──► Keycloak
                  │
                  └── LDAP lookup / password validation ──► LDAP/AD
                  │
                  └──► complete app login

  Brokering path (authentication happens at external IdP)
  ───────────────────────────────────────────────────────
  Browser ──► Keycloak ──► redirect ──► Upstream IdP
                    ▲                       │
                    └──── browser returns ──┘
                    │
                    └──► complete app login

What that comparison shows:

• Federation path: the browser stays with Keycloak for login. Keycloak talks to LDAP/AD in the background for lookup and password validation, then completes the application login.
• Brokering path: Keycloak redirects the browser to the upstream IdP. After that IdP authenticates the user, the browser returns to Keycloak, and Keycloak then completes the application login.
• In both paths, the application trusts Keycloak. LDAP or the upstream IdP is never the direct IdP for the app in these sketches.
• The main login-flow difference is where authentication happens: against the directory behind Keycloak, or at the upstream IdP after a browser redirect.

Both paths can still give you SSO across applications that trust the same Keycloak realm. User sync, mappers, and account creation also differ, which the later sections cover.

User Storage, Import and Synchronization

User federation (LDAP/AD)

When Import Users is enabled, Keycloak stores LDAP users in its local database when they are first encountered through login or lookup. Synchronization can also import users in bulk. Passwords are never imported; password validation stays on LDAP. If you disable import, Keycloak can still authenticate against LDAP without keeping a full local copy. Some Keycloak features then need data that LDAP cannot supply, so those features may not work.

LDAP Edit Mode controls whether Keycloak can update the directory. READ_ONLY blocks writes back to LDAP. Writable modes allow supported user changes to be sent to the directory.

Identity brokering

On first login with no linked account yet, Keycloak usually creates a local user (or links one) through the First Login Flow. Later logins for an already-linked identity reuse that account. Identity provider mappers and Sync Mode can still update attributes on those later logins. Keycloak does not walk the upstream directory on a schedule the way LDAP sync can.

Keycloak also does not continuously poll an upstream IdP for account status. If the upstream account is disabled, that usually shows up on a later authentication with that provider. An existing Keycloak session does not automatically mirror the upstream account. Whether logout or session changes reach applications depends on the provider and protocol setup.

Those local users still appear under Users in the Admin Console, with a link back to the identity provider.

Mappers and Attribute Handling

Both features map external data into Keycloak’s user model. They live in different Admin Console places and fire at different times.

LDAP mapper vs IdP mapper vs protocol mapper

Mappers sit on the path from an external source into Keycloak, and then from Keycloak out to applications. The diagram below shows those two directions for LDAP/AD federation and for an external IdP.

  External source
        │
        ├─ LDAP/AD ──────► LDAP mapper ───────────────► Keycloak user model
        │                                                   │
        └─ External IdP ─► Identity Provider mapper ────────┤
                                                            │
                                                            ▼
                                                     Protocol mapper
                                                            │
                                                            ▼
                                                   Token / SAML assertion

What that diagram shows:

• Top branch: LDAP or Active Directory data enters Keycloak through LDAP mappers on the LDAP federation provider. LDAP mappers are invoked as the LDAP provider reads or synchronizes users and related LDAP data into Keycloak, including during login and user lookup.
• Bottom branch: claims or assertion attributes from an external IdP enter Keycloak through identity provider mappers during a brokered login.
• Shared middle: both branches land on the same Keycloak user model. That is the account your Admin Console lists under Users.
• Outbound path: protocol mappers use Keycloak user, role, group, and session information to shape claims in tokens or SAML assertions sent to applications.

LDAP mappers and IdP mappers control how external identity data enters Keycloak. Protocol mappers control how Keycloak data leaves Keycloak toward applications.

LDAP mappers map directory data into Keycloak for people who authenticate through that store. IdP mappers shape what arrives from one brokered login. An OIDC broker alone will not import every LDAP group from Active Directory. If groups live in AD and you need them as Keycloak groups, use LDAP federation (or a groups claim from the IdP).

When to Use Each Approach

Choose user federation when:

• LDAP or Active Directory is where employee accounts are managed (the system of record)
• You want password validation to stay in the directory
• You need group membership from the directory inside Keycloak
• Applications should talk only to Keycloak, while HR and IT keep managing accounts in AD

Choose identity brokering when:

• Another organization or cloud IdP already authenticates the user (partner SSO, Entra ID, Okta, Google Workspace)
• You need social login buttons
• You cannot (or must not) bind to LDAP from the Keycloak host
• Upstream MFA and conditional access should stay under the external IdP’s control

Use the Admin Console names so the choice stays clear: User federation for external user stores, Identity providers for brokered authentication.

Can You Use Both Together?

Yes. One realm can have LDAP user federation and one or more identity providers at the same time.

Common patterns:

• Employees authenticate against AD through user federation; contractors click “Sign in with partner IdP” through brokering
• Most users use brokered Entra ID login; a small LDAP provider remains for a legacy population still in an old directory

The sketch below is one realm with both attachments. Applications still talk only to Keycloak. LDAP is a direct Keycloak-to-directory connection; the external IdP path goes through the browser.

                              ┌──────────────────┐
                              │    LDAP / AD     │
                              └────────▲─────────┘
                                       │
                                LDAP lookup /
                              password validation
                                       │
                                       │
  Applications ◄──► Browser ◄──► Keycloak realm
                                       │
                                       │ browser redirect /
                                       │ return
                                       ▼
                                External IdP
                             (Entra / Okta / …)

What that diagram shows:

• Apps and the browser always meet Keycloak for login. Apps do not bind to LDAP or call Entra directly in this design.
• Upper branch: Keycloak talks to LDAP/AD over LDAP for lookup and credential validation when that federation provider is configured. That path does not redirect the browser to the directory.
• Lower branch: for brokering, Keycloak redirects the browser to an external IdP such as Entra ID or Okta, then the browser returns to Keycloak with the IdP response.
• Both paths meet in the same realm, so clients, roles, and SSO sessions can be shared after each path succeeds.

If the same person exists in both LDAP and an external IdP, plan how Keycloak should link those identities before you enable both. Otherwise the First Login Flow may find an existing account with the same email and ask for account-linking verification.

Active Directory vs Entra ID: Which Keycloak Feature?

Product names alone do not pick the Admin Console screen. The interface Keycloak uses does.

If Keycloak connects directly to AD through LDAP, that is federation. If an AD-backed environment exposes authentication through AD FS, Entra ID, or another SAML/OIDC IdP, Keycloak is brokering authentication instead.

Summary

LDAP, Active Directory, or a custom user store belong under User federation. External login through Entra ID, Okta, Google, or another IdP (OIDC, SAML, OAuth 2.0, or social) belongs under Identity providers, which is Keycloak’s identity-brokering model. You can enable both in one realm when different groups of users need different sources.

Stick to the Admin Console names when you read docs or search results. When a brokering chapter says “federated identity,” it means a linked IdP account, not the LDAP User federation feature.

References

• Keycloak Server Administration Guide — User storage federation
• Keycloak Server Administration Guide — LDAP and Active Directory
• Keycloak Server Administration Guide — Identity brokering
• Keycloak Server Administration Guide — First login flow