Keycloak Active Directory Groups Not Syncing

Sync LDAP groups to Keycloak can report zero imports while user federation still binds, or groups can appear in Keycloak while a user’s Groups tab stays empty. On Active Directory, those symptoms usually trace to LDAP Groups DN scope, how the group mapper reads membership (memberOf vs recursive retrieval), or confusion between nested AD groups and what AD stores on each user.

Use ldapsearch on the RHEL host where Keycloak runs with the same bind DN, LDAP Groups DN, and membership attributes the mapper uses. This guide assumes the ad-groups mapper you configured during Active Directory group-to-role mapping. If users never imported, fix Active Directory user sync before you tune group membership.

Keycloak AD Groups Not Syncing or 0 Imported Groups: Quick Fix

If Sync LDAP groups to Keycloak returns 0 imported groups or users lack AD groups in Keycloak, check these in order:

1. LDAP Groups DN — does it contain the security group objects you expect (not only users)?
2. Group object classes and filters — AD groups use group; a custom filter can exclude every group.
3. Sync LDAP groups — run it on the group-ldap-mapper, not only Sync all users on the provider.
4. User roles retrieve strategy — memberOf returns only direct groups on the user; nested parent groups need the AD recursive strategy.
5. Preserve group inheritance — controls the Keycloak group tree, not transitive user membership by itself.
6. User import — federated users must exist before membership appears on the user record.

Mirror LDAP Groups DN and filters with ldapsearch. If LDAP does not return the group object, Keycloak cannot import it.

Group sync imports group objects; user membership is resolved separately when the user logs in or when you refresh federation.

How Keycloak syncs Active Directory groups

The group-ldap-mapper on lab-ad searches LDAP Groups DN for group objects and creates Keycloak groups. Sync LDAP groups to Keycloak bulk-imports or updates those objects. Whether a user belongs to a group depends on User roles retrieve strategy and the Member-of LDAP attribute (usually memberOf on AD).

   group-ldap-mapper (ad-groups)
              |
    LDAP Groups DN search
              v
     AD group objects (cn)
              v
 Sync LDAP groups → Keycloak /Groups
              |
   User login / federation refresh
              v
 memberOf or recursive member search
              v
 User → Groups membership in Keycloak

Realm golinuxcloud and mapper ad-groups match the group-to-role mapping guide.

Fix missing or zero imported AD groups

Start with the settings that define which group objects Keycloak can see:

1. Open User federation → lab-ad → Mappers → ad-groups.
2. Confirm LDAP Groups DN and Group object classes.
3. Run Sync LDAP groups to Keycloak on the mapper.
4. Confirm groups under Groups in the realm.

If LDAP returns no group entries under LDAP Groups DN, group sync can finish with zero imported groups even when Test connection on the provider succeeds.

Starting point (lab)

Where to run LDAP commands

Run ldapsearch on the RHEL host where Keycloak runs, not on the domain controller and not inside the Keycloak container:

sudo dnf install -y openldap-clients

Set StartTLS trust once per shell (same PEM as the integration guide):

export LDAPTLS_CACERT=~/keycloak-ad-lab/trust/lab-dc.pem

The host must resolve win-8s0k67ep5eo.lab.example, reach port 389, and trust the DC certificate used for StartTLS.

Check LDAP Groups DN and Builtin vs OU groups

Application security groups usually live in an OU you manage (OU=Keycloak,DC=lab,DC=example). Built-in AD groups live under CN=Builtin,DC=lab,DC=example (a CN container, not OU=Builtin). Pointing LDAP Groups DN at the wrong container either imports nothing useful or pulls dozens of built-in groups you never mapped.

Test LDAP Groups DN with ldapsearch

List group objects under the OU Keycloak should sync (-W prompts for the bind password):

ldapsearch -x -ZZ -H ldap://win-8s0k67ep5eo.lab.example:389 \
  -D "keycloak-bind@lab.example" -W \
  -b "OU=Keycloak,DC=lab,DC=example" -s sub "(objectClass=group)" cn

Sample output:

dn: CN=KC-App-Admins,OU=Keycloak,DC=lab,DC=example
cn: KC-App-Admins

dn: CN=KC-App-Users,OU=Keycloak,DC=lab,DC=example
cn: KC-App-Users

dn: CN=KC-App-Developers,OU=Keycloak,DC=lab,DC=example
cn: KC-App-Developers

Three cn lines mean Keycloak can import three groups when LDAP Groups DN matches this OU.

To see why CN=Builtin is a poor default for application roles, count built-in groups at one level:

ldapsearch -x -ZZ -H ldap://win-8s0k67ep5eo.lab.example:389 \
  -D "keycloak-bind@lab.example" -W \
  -b "CN=Builtin,DC=lab,DC=example" -s one "(objectClass=group)" cn

On the lab DC, that search returned 29 cn lines (for example Administrators under CN=Builtin,DC=lab,DC=example). Keep LDAP Groups DN on your application OU unless you intentionally import built-in groups.

Application groups such as KC-App-Admins are not stored under CN=Users. A subtree search from CN=Users,DC=lab,DC=example for KC-App-Admins returns no group entry, which is why LDAP Groups DN must target the OU that actually holds your security groups.

Check User roles retrieve strategy and memberOf

Active Directory maintains each user’s direct group memberships in memberOf. If a group contains another group, the member attribute on the parent lists the child group, but users in the child group do not automatically gain the parent in memberOf.

Nested AD groups vs memberOf on the user

In the lab, KC-App-Users lists KC-App-Developers as a member (group nesting). User jane is a member of KC-App-Developers but her memberOf does not include KC-App-Users:

Confirm nesting on the parent group:

ldapsearch -x -ZZ -H ldap://win-8s0k67ep5eo.lab.example:389 \
  -D "keycloak-bind@lab.example" -W \
  -b "OU=Keycloak,DC=lab,DC=example" -s sub "(cn=KC-App-Users)" member

Sample output:

member: CN=KC-App-Developers,OU=Keycloak,DC=lab,DC=example

Read memberOf for the same user Keycloak federates:

ldapsearch -x -ZZ -H ldap://win-8s0k67ep5eo.lab.example:389 \
  -D "keycloak-bind@lab.example" -W \
  -b "DC=lab,DC=example" -s sub "(sAMAccountName=jane)" memberOf

Sample output:

memberOf: CN=KC-App-Developers,OU=Keycloak,DC=lab,DC=example
memberOf: CN=KC-App-Admins,OU=Keycloak,DC=lab,DC=example
memberOf: CN=Network-Admins,CN=Users,DC=lab,DC=example

KC-App-Users is absent because AD does not add parent groups to memberOf for users who are only in the child group.

Preserve group inheritance builds /KC-App-Users/KC-App-Developers in the Keycloak group tree. It does not replace recursive membership: a user with only KC-App-Developers on memberOf still needs the recursive strategy to appear in the parent Keycloak group for role mappings on KC-App-Users.

After you change retrieve strategy, have the user sign in again or refresh federation, then open Users → the account → Groups.

Verify group sync and user membership

1. Set LDAP Groups DN to an OU that ldapsearch lists with your application groups.
2. Run Sync LDAP groups to Keycloak on ad-groups.
3. Open Groups and confirm KC-App-Admins and nested paths when Preserve group inheritance is on.
4. Run Sync all users on lab-ad if the account is not already federated.
5. Open Users → kc-roleuser → Groups and confirm KC-App-Admins when memberOf includes that group.

When groups already exist, sync may report 0 imported groups, 3 updated groups instead of new imports. That is normal on a realm that already ran the mapping guide.

Troubleshoot Keycloak AD group sync

Summary

When Active Directory groups do not appear in Keycloak, first confirm LDAP Groups DN returns your security groups with ldapsearch. Built-in groups under CN=Builtin and application groups under a dedicated OU are different targets; swapping CN and OU in the DN is a common misconfiguration.

Group sync imports objects; user membership follows User roles retrieve strategy. With memberOf, users receive only groups AD lists on their account. Nested AD groups such as KC-App-Users → KC-App-Developers require recursive retrieval if users should inherit parent groups without direct memberOf entries.

After LDAP Groups DN and retrieve strategy match AD, run Sync LDAP groups to Keycloak, sync users if needed, and confirm memberships on the federated user. Return to the group-to-role mapping walkthrough when you need realm role assignment on imported groups.

References

• Keycloak Server Administration Guide — LDAP mappers and sync
• Keycloak Server Administration Guide — LDAP user federation
• Microsoft Learn — Active Directory security groups