Keycloak LDAP Groups
You set up keycloak ldap groups by linking an external directory and adding a group mapper. This mapper reads group records from your directory and copies them into your identity store. Many teams use this setup to manage user logins from one central place. Still, broad directory groups often grant too much power to every member inside the group. A single shared role can expose production systems to dangerous commands or data leaks. How keycloak ldap groups work in practice First, an admin li
Keycloak + LDAP Directory Services: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up keycloak ldap groups by linking an external directory and adding a group mapper. This mapper reads group records from your directory and copies them into your identity store. Many teams use this setup to manage user logins from one central place. Still, broad directory groups often grant too much power to every member inside the group. A single shared role can expose production systems to dangerous commands or data leaks.
How keycloak ldap groups work in practice
First, an admin links the identity server to the external directory service. The server needs a bind account and a base path to find user records. Once the user link works, the admin adds a group mapper to the provider. This mapper points to the exact folder where group objects live in the directory. It also defines which attribute connects a user record to a group record.
You can choose how the server handles changes between the two systems. In read-only mode, the directory stays the single source of truth for all memberships. In import mode, the server saves a local copy of the group list during login. Teams can also run background tasks to sync new group changes on a set timer. Some setups preserve nested group trees so child teams inherit parent roles.
After the sync finishes, the server needs to pass these groups to downstream apps. Admins add a client scope mapper to put group names inside JSON web tokens. When an engineer logs in, the app reads the token claims to check their team. This workflow keeps team rosters in one place and avoids manual account work.
Why group sync needs a broader security view
Syncing directory groups solves the first step of identity control for your engineering team. It proves who the person is and which team they belong to at login time. When someone leaves the company, removing them from the directory blocks their next login. This central check saves time and keeps user lists clean across many tools.
Still, directory groups only control the front door to a system or database. Once a user logs in, the identity provider steps out of the way. The directory cannot see what SQL queries or shell commands the user runs next. If a developer belongs to a broad group, they keep those wide permissions all day.
Keycloak + LDAP Directory Services: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Static groups also struggle when someone needs temporary rights to fix a production bug. Admins often add the user to a high-level group and forget to remove them later. Over time, this habit leads to privilege creep across your whole engineering team. Even worse, raw queries can return sensitive fields like emails, phone numbers, or card numbers. A simple group check at login cannot rewrite those fields in query results. True safety requires checking and governing every action while the session is active.
Best practices for directory group design
Start by keeping your directory tree flat and easy for admins to read. Deeply nested groups make it hard to trace how a user got a specific role. Create clear groups based on job duties rather than broad department names. Filter your mapper so the identity server only pulls groups meant for technical systems. This filter stops clutter and keeps your identity tokens small and fast.
Next, review your group memberships on a regular schedule with team leads. Remove old accounts and shrink groups that grant write permissions to live data. Pair your directory roles with fine-grained rules at the database and server level. When login identity meets active session control, your team stays fast and safe.
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
How do I pass synced LDAP groups into an OIDC token?
Add a group membership mapper to your client scope in the admin console. This setting writes the user's group names into the token claim at login.
Why are my new directory groups missing after I link the server?
Check that your group mapper points to the right directory folder and member attribute. You may also need to trigger a manual group sync to pull recent changes.
Can I restrict which LDAP groups sync into the identity store?
Yes, you can add a custom LDAP filter inside the group mapper settings. The server will only import groups that match your specific filter rules.