Keycloak中用户组映射JWT失败，实际映射Realm角色问题

这不是bug，是Keycloak预定义映射器的命名陷阱——它叫groups，但实际功能是映射Realm角色，和用户所属的组完全无关，属于官方设计的命名误导。

要把用户组信息添加到JWT的claim中，必须使用Group Membership类型的自定义映射器，具体操作：

• 进入目标客户端的Client Scopes页面，选中你的专属client scope（比如client-dedicated）
• 切换到Mappers标签页，点击Create新建映射器
• 映射器类型选择Group Membership（别再选那个坑人的预定义groups映射器）
• 配置参数：
  • Name：自定义一个易识别的名称，比如user-group-mapper
  • Token Claim Name：设置你想要的claim字段名，比如user_groups或直接groups
  • 根据需求勾选Add to ID token和Add to access token
  • Full group path：如果需要完整的组层级路径（例如/admin/sub-admin）就勾选，否则仅显示组名称
• 保存设置后，重新获取JWT token，就能在claim中看到用户的实际所属组数据了

那个预定义的groups映射器是Keycloak版本迭代遗留的历史问题，它的逻辑就是读取并映射Realm角色，和用户组没有任何关联，所以选它只会得到角色信息而非组信息。

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