本文介绍在 JavaEE + Tomcat 环境中，使用 pac4j-oidc 集成 Keycloak 时，如何正确获取用户在 Keycloak 中所属的 Groups，而非仅限于 Realm 或 Client Roles，并说明推荐使用 KeycloakRolesAuthorizationGenerator 及自定义属性映射的实践方法。
本文介绍在 javaee + tomcat 环境中，使用 pac4j-oidc 集成 keycloak 时，如何正确获取用户在 keycloak 中所属的 groups，而非仅限于 realm 或 client roles，并说明推荐使用 `keycloakrolesauthorizationgenerator` 及自定义属性映射的实践方法。
在基于 pac4j 的 Keycloak OIDC 集成中，UserProfile 默认仅暴露标准 OpenID Connect 声明（如 sub, name, email）及通过 roles 声明映射的 Realm/Client Roles。但 Keycloak 中的 Groups（群组） 并非 OIDC 标准声明，因此不会自动出现在 UserProfile.getRoles() 中——这也是开发者常遇到的困惑根源。
✅ 正确做法是：启用 KeycloakRolesAuthorizationGenerator
该类专为 Keycloak 设计，可将 Keycloak 用户的 Groups（以及 Realm Roles、Client Roles）统一提取并注入到 UserProfile 的授权信息中。它并非简单返回字符串列表，而是将 Groups 映射为 UserProfile 的 groups 属性（类型为 List
// 在认证成功后，从 WebContext 获取 UserProfile
UserProfile profile = webContext.getSessionStore().get(true, webContext);
// ✅ 正确获取 Keycloak Groups（需已配置 KeycloakRolesAuthorizationGenerator）
List<string> groups = profile.getAttribute("groups", List.class);
if (groups != null) {
groups.forEach(group -> System.out.println("Member of group: " + group));
}</string>
? 关键前提：
- 使用 KeycloakOidcClient（而非泛型 OidcClient）；
- 在客户端配置中启用 KeycloakRolesAuthorizationGenerator，例如：
KeycloakOidcClient client = new KeycloakOidcClient(); client.setAuthorizationGenerator(new KeycloakRolesAuthorizationGenerator()); // 其他配置：setClientId, setSecret, setDiscoveryUri 等...
⚠️ 注意事项：
Keycloak 默认 不将 Groups 发送到 Access Token 或 ID Token。需在 Keycloak Admin Console 中为对应 Client 配置 Group Membership Mapper：
→ 进入 Clients → Your-Client → Mappers → Create
→ Type: Group Membership
→ Token Claim Name: groups（与代码中 getAttribute("groups") 保持一致）
→ Add to ID token / Access token / User Info: ✅ 勾选至少一项（推荐勾选 Access Token 和 User Info）若需更细粒度控制（如嵌套群组路径、过滤特定群组），可继承 KeycloakRolesAuthorizationGenerator 并重写 generate 方法，或实现自定义 AuthorizationGenerator。
? 补充技巧：
除 groups 外，其他 Keycloak 自定义属性（如 department, employeeId）也可通过相同方式获取：
String dept = profile.getAttribute("department", String.class);
前提是这些属性已在 Keycloak 中通过 User Attribute Mapper 正确映射至令牌。
总结：获取 Keycloak Groups 不依赖“手动调用 Admin REST API”，而应充分利用 pac4j 生态提供的 KeycloakRolesAuthorizationGenerator + Keycloak Token Mapper 组合方案——既符合 OAuth2/OIDC 最佳实践，又保持代码简洁、安全与可维护性。
