Keycloak LDAP Group Mapper
A keycloak ldap group mapper syncs user groups from an external directory into your realm. You set it up by linking your directory tree to local group rules. Platform teams use this tool to manage user roles in one central place. When a person joins a team in the directory, they get that group right away. Still, directory groups often give broad, static rights that stay active all day. If a broad group links to a production role, too many people keep admin power. How the keycloak ldap group ma
Keycloak + LDAP Directory Services: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
A keycloak ldap group mapper syncs user groups from an external directory into your realm. You set it up by linking your directory tree to local group rules. Platform teams use this tool to manage user roles in one central place. When a person joins a team in the directory, they get that group right away. Still, directory groups often give broad, static rights that stay active all day. If a broad group links to a production role, too many people keep admin power.
How the keycloak ldap group mapper works
Your directory server stores users and groups as separate records in a tree structure. The identity server needs a way to read both trees and connect them together. You start by setting up a user federation link to your directory server. Then you add the group mapper to that federation link. You point the mapper to the exact branch where your directory stores group records.
Next, you tell the mapper how your directory links users to those groups. Some directories list member names inside the group record itself. Other directories store group names as an attribute on the user record. The mapper reads this link when a user logs in or during a sync job. It creates matching groups inside your realm and puts the user in them.
You can also choose how the server handles changes made inside the local realm. In read-only mode, the server only reads group data from your directory. It blocks local edits so your external directory stays the single source of truth. In read-write mode, local group changes write back to your directory tree. Most teams pick read-only mode to keep directory rules clean and safe. Finally, token mappers put those group names into the token sent to your apps.
Sync modes and group hierarchy design
Directory trees often contain nested groups where one team sits inside a larger department. The mapper can keep this parent and child structure or flatten all groups into one list. Keeping the tree structure helps when child groups inherit roles from a parent group. Flattening the list works better when downstream apps only check simple group names. You should match this setting to how your apps read token claims.
Sync timing also shapes how fast access changes take effect across your systems. On-demand sync checks a user's groups only when that user logs into a session. Periodic sync runs on a timer to pull bulk changes from the directory server. If you remove a user from an admin group, old tokens still work until expiry. Teams must keep token lifetimes short so group changes apply fast.
Keycloak + LDAP Directory Services: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What directory group mapping solves and what it misses
Syncing directory groups saves time and cuts down on manual account work. You do not have to build user lists twice when someone joins or leaves. When HR disables a user in the main directory, login rights stop across connected apps. It gives you a clear way to assign high-level roles across many tools at once.
Still, directory groups only decide who can log in at the start of a session. They cannot see or control what a user does after the session starts. A database group might let a developer log into a production data store. Once inside, that group check cannot stop a bad write command or a bulk dump. It also cannot rewrite sensitive fields like emails, phone numbers, or card numbers in results. Directory groups are too coarse to approve single commands or log every query run.
Add runtime guardrails and masking beside your databases and APIs
Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits beside the service as an open-source proxy, a sidecar for your database or API.
Before a query runs, hoop.dev guardrails check the statement against your rules. An AI Analyzer you configure can score intent or hold risky calls for human review. Next, hoop.dev data masking rewrites sensitive fields in responses, and each verdict is logged per listener. Explore the MIT-licensed project on GitHub.
Frequently asked questions
What is the difference between a group mapper and a role mapper?
A group mapper pulls directory groups into your realm as group objects that hold users. A role mapper turns directory groups straight into flat role labels for access checks.
Why are new directory groups not showing up for a user?
The group might sit outside the search branch you set up in the mapper. You may also need to run a manual sync or wait for a fresh login.
Should I use read-only or read-write mode for directory groups?
Use read-only mode if your central directory is the single source of truth for teams. Use read-write mode only if admins must edit directory memberships from the identity server.