Keycloak：如何清理LDAP同步的非过滤组或实现按Filter同步组？

问题背景 #

在Keycloak中配置LDAP组同步后，更新LDAP Filter并重新执行普通同步操作时，之前同步的不符合过滤条件的组并未被移除，Keycloak仍保留全部同步过的组。

解决方案 #

方案1：使用「带移除的全量同步」（推荐） #

Keycloak默认的同步操作仅会新增/更新符合条件的组，不会主动删除旧的非匹配组，需使用特定同步模式：

• 进入Keycloak控制台，依次导航到 User Federation > 你的LDAP提供商（注意是LDAP配置主页面，不是mapper页面）
• 找到「Synchronization」区域，点击Sync LDAP Groups to Keycloak旁的下拉菜单，选择Full Sync with Remove
• 执行同步操作，Keycloak会自动对比LDAP中当前符合过滤条件的组，删除Keycloak内存在但LDAP中已不存在（或不符合过滤规则）的组

方案2：手动清理后重新同步 #

如果强制同步未生效，或需要彻底重置组数据：

控制台批量删除

• 进入Keycloak的 Groups 页面，勾选所有由LDAP同步生成的组（可通过组名称/描述识别，通常会带有LDAP相关标识）
• 点击顶部的「Delete」按钮批量删除

Keycloak CLI命令清理

1. 进入Keycloak安装目录的bin文件夹，先登录管理员账户：

   # Linux/macOS
   ./kc.sh adm config credentials --server http://localhost:8080 --realm master --user admin --password 你的管理员密码
   
   # Windows
   kc.bat adm config credentials --server http://localhost:8080 --realm master --user admin --password 你的管理员密码
   

2. 列出当前Realm的所有组（确认待删除目标）：

   ./kc.sh adm groups list --realm 你的Realm名称
   

3. 批量删除所有组（或指定组）：

   # 删除所有组
   ./kc.sh adm groups delete --realm 你的Realm名称 --all
   
   # 仅删除指定组（替换为组名）
   ./kc.sh adm groups delete --realm 你的Realm名称 --name "要删除的组名"
   

4. 重新执行LDAP组同步操作

注意事项 #

• 确认LDAP Filter语法正确，例如(objectClass=groupOfNames)或自定义的过滤规则，避免因过滤条件错误导致同步异常
• 执行「带移除的全量同步」前，建议备份Keycloak数据库，防止误删重要组数据
• 多Realm环境下，确保操作的是目标业务Realm，而非默认的master Realm

内容的提问来源于stack exchange，提问作者GereG