Keycloak 23.0.0中JWT Token无法携带用户组的问题求助

问题描述 #

使用Keycloak 23.0.0版本，配置默认客户端作用域的Group Membership映射器后，通过直接授权流（Resource Owner Password Credentials Grant）生成的access token中未包含用户组信息。已检查用户组、用户配置及映射器截图，均无异常，当前生成的JWT内容如下：

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "vL8kIqWQFfX6oj-gN64xZibBqQuV3JzXqKkwGp5KU3Y"
}.
{
  "exp": 1692262142,
  "iat": 1692258542,
  "jti": "32620dd7-3dc9-464f-af49-153ba3d389d0",
  "iss": "https://example.com/realms/domain_acl",
  "aud": "account",
  "sub": "46e82311-a784-4c2f-b1ef-057ca127f18b",
  "typ": "Bearer",
  "azp": "api-client",
  "session_state": "e9fbc2b8-b548-423a-8f5a-8469c0a92eb5",
  "acr": "1",
  "realm_access": {
    "roles": [
      "******",
      "*******"
    ]
  },
  "resource_access": {
    "account": {
      "roles": [
        "manage-account",
        "manage-account-links",
        "view-profile"
      ]
    }
  },
  "scope": "profile email",
  "sid": "e9fbc2b8-b548-423a-8f5a-8469c0a92eb5",
  "email_verified": false,
  "name": "domain ACl",
  "preferred_username": "dev",
  "given_name": "domain ACl",
  "email": "dev@example.com"
}.
[signature]

排查与解决步骤 #

1. 核对Group Membership映射器核心配置 #

• 确认Add to access token选项已勾选：映射器默认可能仅注入id token，必须手动勾选该选项才能将组信息添加到access token
• 检查Token Claim Name：建议设为groups，确保字段名符合预期
• 确认Claim JSON Type为Array：用户组是多值数据，需用数组类型返回
• 勾选Multivalued：支持用户同时属于多个组的场景
• 若用户组存在层级结构，按需勾选Full group path，平级组保持默认即可

2. 确认客户端作用域关联正确 #

• 带有Group映射器的客户端作用域必须添加到默认客户端作用域（Default Client Scopes），而非可选作用域（Optional）
• 进入Clients -> api-client -> Client Scopes标签，确认该作用域在Default列表中，而非Optional

3. 调整直接授权流的请求参数 #

• 若映射器设置了关联的scope（比如groups），请求时必须在scope参数中包含该值，示例：scope=profile email groups
• 若不想手动指定scope，可开启客户端的Full Scope Allowed选项（Clients -> api-client -> Settings），自动包含所有默认作用域的映射器

4. 检查客户端与用户组状态 #

• 确认api-client的Access Type配置正确：若为confidential，请求时必须携带client_secret参数
• 检查用户所属组的Enabled状态为开启：Keycloak组默认启用，需确认未被手动禁用
• 验证用户与目标组的关联：进入Users -> 目标用户 -> Groups标签，确认组已正确绑定

5. 调试验证 #

• 用Keycloak管理控制台的Clients -> api-client -> Credentials页面的Test Clients功能生成token，对比是否包含组信息，排查直接授权流请求的问题
• 用jwt.io解析token，查看完整的claim内容，避免遗漏关键信息

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