LDAP User Federation

What is user federation?

User federation lets Keycloak read (and optionally write) user accounts from an external store instead of its own internal database. The most common store is LDAP (Lightweight Directory Access Protocol), which is the protocol used by:

• OpenLDAP — the open-source LDAP server.
• Microsoft Active Directory (AD) — the enterprise directory service found in most corporate networks.
• Apache Directory Server, 389 Directory Server, and others.

When a user tries to log in, Keycloak looks them up in the LDAP directory and delegates the password check to the LDAP bind. From the user’s perspective, they are just logging in with their normal directory credentials.

Step 1 — add an LDAP provider

1. In the admin console, make sure you are in the correct realm.
2. Click User federation in the left sidebar.
3. Click Add provider and select LDAP.
4. Keycloak displays the LDAP configuration form.

Step 2 — connection settings

Fill in the connection details:

Field	What to enter
Vendor	Select Active Directory for AD, or Other for OpenLDAP. This pre-fills sensible defaults for DN structures and attributes.
Connection URL	The LDAP server URI, e.g., ldap://ldap.example.com:389 or ldaps://ldap.example.com:636 (LDAPS for encrypted).
Enable StartTLS	Preferred alternative to LDAPS for encrypting the connection on port 389.
Connection pooling	Enable in production to reuse LDAP connections.

Click Test connection to verify Keycloak can reach the server before continuing.

Step 3 — bind settings

Keycloak needs a service account to search the directory. This is called the bind DN.

Field	What to enter
Bind type	simple for username/password bind.
Bind DN	The distinguished name of the service account, e.g., cn=keycloak-svc,ou=service-accounts,dc=example,dc=com.
Bind credentials	The service account password. Store this in a Keycloak vault or environment variable — never hardcode it.

Click Test authentication to verify the bind credentials work.

Step 4 — LDAP searching and user DN

Field	What to enter
Users DN	The base DN to search for users, e.g., ou=users,dc=example,dc=com.
Username LDAP attribute	The LDAP attribute that maps to the Keycloak username. For AD use sAMAccountName; for OpenLDAP use uid.
RDN LDAP attribute	Usually cn or the same as the username attribute.
UUID LDAP attribute	For AD: objectGUID. For OpenLDAP: entryUUID. This is used as Keycloak’s internal user ID.
User object classes	For AD: person, organizationalPerson, user. For OpenLDAP: inetOrgPerson, organizationalPerson.

Step 5 — edit mode and import

These two settings define how Keycloak synchronises users and whether it writes back to LDAP.

Edit mode

READ_ONLY   — Keycloak cannot modify any LDAP attributes. Password changes are rejected. Use for corporate AD where Keycloak should not touch the directory.
WRITABLE    — Keycloak can update LDAP attributes and sync password changes back to LDAP. Use only if Keycloak is authorised to write to the directory.
UNSYNCED    — Keycloak stores attribute changes locally (in its own DB) without writing to LDAP.

# Recommended default for most deployments
Edit mode: READ_ONLY

Copy recommendation ⧉

Import users

• On (default) — Keycloak imports user records into its local database on first login and after each sync. Queries are fast because they hit the local DB.
• Off — Keycloak queries LDAP on every login. Less data stored locally, but every authentication hits the LDAP server.

Step 6 — sync and save

1. Click Save.
2. Back on the User federation page, open your LDAP provider.
3. Scroll down to the Synchronization section.
4. Click Synchronize all users to do an immediate full sync, or configure Changed users sync to run periodically.

After the sync, go to Users in the left sidebar. You should see your LDAP users listed with a “federated” badge.

🔐 Choose READ_ONLY unless you intend to write back to LDAP

The edit mode READ_ONLY prevents Keycloak from modifying your LDAP directory. This is the safe default for corporate Active Directory deployments where the HR system or IT team owns the directory. Only switch to WRITABLE if your organisation has explicitly approved Keycloak as a write-capable client of the directory.

Trade-offs

Option	Benefit	Cost
READ_ONLY	Safest — Keycloak can never write back to LDAP, so there’s no risk of breaking the organisation’s directory. Ideal for a corporate AD owned by IT	Users cannot change their password or profile through Keycloak; they must do it in the source system (e.g. AD)
WRITABLE	Users can change their password or attributes directly through Keycloak — convenient for self-service	Keycloak can write to the production directory — a misconfiguration or a compromised service account can affect real LDAP/AD data organisation-wide
UNSYNCED	Stores attribute changes locally (in Keycloak’s own database) without touching LDAP at all — flexible for extra attributes LDAP doesn’t have	Data in Keycloak and LDAP can diverge over time, because local overrides never sync back to the source of truth

Common mistakes

• Importing all users from a large directory unpaged — for a directory with tens or hundreds of thousands of users, an unpaged sync can crash the LDAP server or Keycloak itself from memory pressure or timeouts. Set a batch size and use paged search if the LDAP server supports it.
• Setting edit mode to WRITABLE without sign-off from whoever owns the directory — Keycloak instantly becomes a client that can write to production AD/LDAP, risking employee data damage if a mapping is wrong. Always start with READ_ONLY and move up only if truly necessary.
• Not configuring connection pooling or a scheduled sync in production — querying LDAP directly on every login (import off) with no connection pooling puts unnecessary load on the LDAP server when many users log in at once.

Real-world example

An organisation bridging Keycloak with an existing Active Directory — employees keep logging in with the same AD password they already use for Windows and email, with no new password to remember and no separate Keycloak account. IT keeps controlling password policy through AD as before.

A company with OpenLDAP as its central employee directory — uses READ_ONLY LDAP federation so every internal tool behind Keycloak sees the same set of users, without syncing data back and forth between multiple systems.

What LDAP attribute should you use as the username for Active Directory?

uid cn sAMAccountName objectGUID

What does LDAP edit mode READ_ONLY mean?

Keycloak can read users but stores all attribute changes locally Keycloak cannot modify any LDAP attributes — password changes are rejected Keycloak reads LDAP only during the initial sync Users can only read their own profile — they cannot change it

What is the purpose of the bind DN in LDAP federation?

It is the base path Keycloak searches for users It identifies the UUID attribute in the directory It is the service account Keycloak uses to query the LDAP directory It defines the edit mode for the federation provider

When "Import users" is turned off, what happens on every login?

Keycloak creates a local copy of the user on first login only Keycloak queries the LDAP server on every authentication Keycloak falls back to its internal user database Keycloak disables password authentication for LDAP users

Submit

Mark as complete