Keycloak：LDAP角色映射至自定义领域角色及API查询用户问题

解决方案1：获取特定复合角色下的所有用户列表 #

Keycloak默认角色用户API不会自动返回复合角色的继承用户，需手动遍历子角色并合并用户列表：

1. 获取复合角色的子角色集合
   调用API获取目标复合角色的直接关联子角色（若存在多层复合，需递归查询子角色的composites）：

   GET /admin/realms/MyRealm/roles/CustomRole1/composites
   

2. 逐个查询子角色的用户
   对每个返回的子角色（如AD_Role1），调用API获取该角色的用户：

   GET /admin/realms/MyRealm/roles/{roleId}/users
   

3. 合并去重用户列表
   将所有子角色的用户列表合并，根据id字段去重，得到复合角色对应的完整用户集合。

也可直接通过用户查询API过滤拥有目标复合角色的用户（Keycloak 19支持该过滤逻辑）：

GET /admin/realms/MyRealm/users?filter=roles=CustomRole1

解决方案2：获取包含角色信息的所有用户列表 #

要获取带完整角色信息的全量用户，需结合用户列表API与角色查询API：

1. 获取全量用户基础信息
   调用API获取所有用户，关闭精简返回模式以获取完整字段：

   GET /admin/realms/MyRealm/users?briefRepresentation=false
   

2. 批量获取用户角色
   对每个返回的用户，调用API获取其所有领域角色（含继承的复合角色）：

   GET /admin/realms/MyRealm/users/{userId}/roles/realm
   

3. 整合用户与角色数据
   将用户基础信息与对应的角色列表整合，得到包含角色信息的完整用户数据集。

解决方案3：同步AD角色时直接分配自定义角色（彻底解决查询问题） #

通过配置LDAP映射器，在AD用户同步阶段直接为用户分配自定义角色，替代复合角色继承逻辑：

单AD角色映射到自定义角色（如AD_Role1 → CustomRole1） #

1. 进入Keycloak管理控制台 → 目标领域MyRealm → User Federation → 选择你的AD LDAP提供商
2. 切换到Mappers标签，点击Add mapper，选择Role LDAP Mapper
3. 配置核心参数：
   • Name: AD_Role1_to_CustomRole1
   • LDAP Role DN: 填写AD中AD_Role1的完整DN（如CN=AD_Role1,OU=Roles,DC=company,DC=com）
   • Role Name: CustomRole1
   • Role Container ID: realm
   • Membership LDAP Attribute: member
   • Membership User LDAP Attribute: distinguishedName
   • Mode: READ_ONLY
4. 保存映射器，触发用户同步即可生效。

多AD角色组合映射到自定义角色（如AD_Role2+AD_Role3 → CustomRole2） #

需通过脚本映射器实现逻辑判断：

1. 在User Federation的Mappers页面，点击Add mapper，选择Script Mapper
2. 配置参数并编写脚本：
   • Name: AD_Roles_to_CustomRole2
   • Script:

     // 获取用户的AD角色集合
     var userAdRoles = ldapContext.getRoles();
     var hasRole2 = false;
     var hasRole3 = false;
     // 检查用户是否同时拥有AD_Role2和AD_Role3
     userAdRoles.forEach(function(role) {
       if (role.getDn() === "CN=AD_Role2,OU=Roles,DC=company,DC=com") {
         hasRole2 = true;
       }
       if (role.getDn() === "CN=AD_Role3,OU=Roles,DC=company,DC=com") {
         hasRole3 = true;
       }
     });
     // 满足条件则分配CustomRole2
     if (hasRole2 && hasRole3) {
       var customRole = realm.getRole("CustomRole2");
       user.grantRole(customRole);
     }
     

3. 保存脚本，重新同步用户后，符合条件的用户会直接被分配CustomRole2，此时调用角色用户API可正常返回结果。

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