Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 37 ยท Identity Brokering and Social Login

LDAP and Active Directory User Federation

Connect Keycloak to LDAP or Active Directory with user federation: connection settings, edit modes, import and sync, LDAP mappers, filters and Kerberos.

Many companies already store people in LDAP or Active Directory. User federation lets Keycloak read (and optionally write) those users, so employees keep one password while your applications use modern OIDC tokens. Federation is different from brokering: with brokering the user is redirected to another system to sign in. With federation Keycloak itself talks to the directory over the network, checks passwords through an LDAP bind, and treats the directory entries as if they were local users.

A directory server cannot run on this site, so the TryIts are stand-ins in JavaScript: an LDAP filter escaper and a small sync simulation. Configuration fields refer to the admin console of recent Keycloak versions.

Adding an LDAP provider

In your realm choose User federation, then Add LDAP providers. The important fields:

  • Vendor: Active Directory, Red Hat Directory Server, Tivoli, Novell eDirectory, or Other. It pre-fills attribute names (AD uses sAMAccountName, others use uid).
  • Connection URL: ldaps://ldap.example.com:636 (prefer LDAPS or StartTLS). Use Test connection after filling it.
  • Bind type and Bind DN / credentials: an account that may search the directory, for example cn=keycloak-svc,ou=service,dc=example,dc=com.
  • Users DN: where users live, such as ou=people,dc=example,dc=com.
  • Username LDAP attribute, RDN LDAP attribute, UUID LDAP attribute, User object classes: these tell Keycloak how entries identify themselves (uid, uid, entryUUID, inetOrgPerson on OpenLDAP; AD uses cn/objectGUID).
  • Custom user LDAP filter: an extra filter that narrows which entries count, for example (memberOf=cn=keycloak-users,ou=groups,dc=example,dc=com).
  • Search scope: one level or the subtree below the Users DN.

Test authentication works with a real account, and use a read-only service account until you understand the edit mode you chose.

flowchart LR
  A["Application"] --> K["Keycloak realm"]
  K -->|"search + bind"| L["LDAP / Active Directory"]
  K --> D[("Keycloak DB: imported copy")]
  L -.->|"periodic sync"| D

Keycloak authenticates against the directory and (by default) keeps an imported copy in its own database.

Edit mode: who may change what

The Edit mode controls writes:

Mode Meaning
READ_ONLY Keycloak only reads; profile and password changes are refused
WRITABLE Changes in Keycloak are written back to the directory
UNSYNCED Changes stay in Keycloak's database only; the directory is untouched

Use READ_ONLY when IT owns the directory, and make sure the account page does not suggest changes that will fail. UNSYNCED is handy when you need extra attributes the directory cannot store.

Import and sync

With Import users on (the default), Keycloak creates a local copy of each user the first time they appear, storing a link to the LDAP entry. Benefits: groups, roles, and sessions work normally; queries are fast. The costs are an extra copy to keep fresh. Synchronization settings provide:

  • Periodic full sync: re-reads everyone, optionally on an interval.
  • Periodic changed users sync: only entries modified since the last sync (needs the vendor's modification timestamp).
  • Remove invalid users: a sync action (or a setting in some versions) removes local copies whose LDAP entry vanished.

Turn import off for a pure pass-through, but then features that need local storage are limited.

JS Stand-in: sync simulation with edit modes

Press Run (or Ctrl + Enter) to see the console output here.

No output.

LDAP mappers

After saving, open the Mappers tab. Defaults map username, email, first name, last name, creation and modify timestamps. You add more mappers to extend the model:

  • user-attribute-ldap-mapper: map any LDAP attribute (such as telephoneNumber) to a user attribute.
  • group-ldap-mapper: mirror LDAP groups into Keycloak groups. Choose the Groups DN and the membership attribute (member).
  • role-ldap-mapper: map LDAP groups or entries to realm or client roles.
  • hardcoded-ldap-role-mapper: give everyone from this directory a fixed role.
  • msad-user-account-control-mapper: translate AD account flags (disabled, password expired) into Keycloak states.
  • certificate-ldap-mapper, full-name-ldap-mapper, and others for special layouts.

After adding a group mapper, use Sync LDAP groups to Keycloak from the mapper's action menu.

Security: LDAP filter injection

Keycloak builds LDAP filters from user input such as the typed username. A filter is a structured string, so characters like *, (, ) and \ must be escaped, otherwise *)(uid=* can widen a search. Keycloak escapes input for you. If you write your own LDAP code, or a custom provider, apply RFC 4515 escaping:

JS Stand-in: escaping a value for an LDAP filter (RFC 4515)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Kerberos and passwords

Keycloak can also use Kerberos (SPNEGO) to sign in domain users without a password prompt. In the LDAP provider, enable Allow Kerberos authentication and configure the realm's Kerberos keytab and principal. Test from a domain-joined machine; browsers must be configured to trust the Keycloak host for negotiation.

Password policy lives in the directory in READ_ONLY and WRITABLE modes. Keycloak password policies do not apply to directory passwords.

Operational tips

  • Always use TLS to the directory and a truststore that contains its CA.
  • Set connection pooling and timeouts so a slow directory cannot hang logins.
  • Watch performance of the periodic sync on very large directories; use "changed users sync".
  • Treat the service account like any privileged credential: store it in the vault, rotate it.
  • When migrating away, use the Unlink users action; with imported users, a prior step may be needed to move credentials.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between federation and brokering?

    With federation Keycloak connects to the directory over LDAP; with brokering the user signs in at an external identity provider.
  2. 2. Which edit mode keeps changes only inside Keycloak's database?

    UNSYNCED lets users edit data in Keycloak without writing anything back to the directory.
  3. 3. Why must filter values be escaped?

    Special characters in user input could widen or alter a search (LDAP injection).
  4. 4. Which mapper mirrors LDAP groups into Keycloak groups?

    The group-ldap-mapper maps a Groups DN and membership attribute to Keycloak groups.

Summary

  • User federation reads and authenticates users from LDAP or Active Directory.
  • Vendor, URLs, DNs, and filters describe how entries look.
  • Edit mode decides whether writes are refused, stored locally, or pushed to the directory.
  • Sync keeps imported copies fresh; mappers bring in attributes, groups, and roles.
  • Escape filter input, use TLS, and guard the service account.

Next: Authorization Services Concepts