Keycloak LDAP Federation
You set up keycloak ldap federation by linking your directory server to a Keycloak realm. Keycloak then reads user accounts and groups from your LDAP tree during login. Platform teams use this setup to keep one source of truth for identities. Yet mapping broad directory groups to database or server roles often grants too much power. One shared role can let an engineer run dangerous commands across production systems. How keycloak ldap federation works in practice Keycloak acts as an identity
Keycloak + Identity Federation: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up keycloak ldap federation by linking your directory server to a Keycloak realm. Keycloak then reads user accounts and groups from your LDAP tree during login. Platform teams use this setup to keep one source of truth for identities. Yet mapping broad directory groups to database or server roles often grants too much power. One shared role can let an engineer run dangerous commands across production systems.
How keycloak ldap federation works in practice
Keycloak acts as an identity provider that sits in front of your directory. Your LDAP server holds user records, passwords, and group memberships in a tree structure. When a user tries to log in, Keycloak checks the LDAP tree first. It binds to the directory server using a dedicated service account and password.
Next, Keycloak searches the directory base path for a matching username or email address. Once it finds the user record, it tests the password against the LDAP server. If the password matches, Keycloak pulls the user profile into its own local database. This step lets Keycloak issue modern tokens for web apps and internal tools.
Teams can choose a read-only mode or a writable mode for this link. Read-only mode keeps the LDAP server as the sole place for password changes. Writable mode lets users update their profiles or passwords inside Keycloak itself. Most security teams pick read-only mode to avoid split records across two systems.
Mapping directory groups and user attributes
Pulling usernames is only the first half of the directory setup process. You also need attribute mappers to translate LDAP fields into Keycloak user tokens. Standard mappers copy first names, last names, and email addresses into the local store. Group mappers read LDAP group objects and turn them into Keycloak roles.
Sync intervals control how often Keycloak checks the directory for recent account changes. A full sync pulls every user record from the LDAP tree on a schedule. A changed-users sync only pulls records modified since the last check ran. If a sync lags, a fired employee might keep active tokens for hours.
Keycloak + Identity Federation: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What directory sync solves and what it leaves open
Directory federation solves the problem of scattered accounts across dozens of company tools. Admins do not have to create local accounts in every single app anymore. When someone joins the team, one LDAP group gives them their needed roles. When they leave, disabling the LDAP account blocks new logins right away.
Still, directory federation only checks who a person is at the login screen. It does not govern what that user does inside a live database session. Once an engineer logs in, their role often allows any query or command. A valid login cannot stop someone from dropping a table by mistake.
Directory roles also cannot filter raw data returning from a production query. If a table holds card numbers or national IDs, the query returns everything. Data masking is needed to rewrite matched fields like emails or phone numbers. Relying only on login groups leaves live commands and sensitive rows wide open.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Does Keycloak store LDAP passwords in its own database?
No, Keycloak does not copy raw passwords from your LDAP directory server. It sends the password back to the LDAP server to check it during login.
What happens if the LDAP server goes offline?
Keycloak can still read cached user profiles, but password checks will fail. Users cannot start new sessions until the directory link comes back online.
How do LDAP group changes reach active user sessions?
Keycloak updates group mappings during login or during a scheduled background sync. Active tokens keep their old roles until they expire and refresh.