如何配置Keycloak使返回的JWT包含用户Realm与Client角色？

针对你使用Keycloak 19.0.0/20.0.1版本，已配置Realm角色映射但JWT未包含roles字段的问题，按以下步骤排查修复：

1. 确认Client已关联realm roles Client Scope #

光配置Mapper没用，得确保目标Client（你的spring-client）已经关联了realm roles这个Scope：

• 进入Keycloak控制台，打开你的Realm，进入Clients -> 选中spring-client -> 切换到Client Scopes标签页
• 查看Assigned Default Client Scopes列表，确认realm roles在其中；如果不在，从Available Client Scopes里选中它，点击Add selected移到已分配列表

2. 检查Realm角色Mapper的配置细节 #

你创建的realm_access.roles映射可能参数有误，按以下标准配置调整：

• 进入Client Scopes -> 选中realm roles -> 切换到Mappers标签页，找到你的角色Mapper
• 确保配置项符合：
  • Mapper类型：User Realm Role
  • Token Claim Name：设为roles（这就是你要在JWT里出现的字段名）
  • Claim JSON Type：选JSON（如果需要返回数组格式的角色列表）
  • 勾选Add to ID token和Add to access token（要JWT里显示就都勾上）
  • 勾选Multivalued（支持多个角色返回数组）
  • 勾选Aggregate attributes（确保合并所有用户的Realm角色）

3. 检查Client的全权限开关 #

如果Client限制了Scope范围，也会导致角色不返回：

• 进入Clients -> spring-client -> Settings标签页，找到Full Scope Allowed，设置为On
• 如果设为Off，需要手动把roles等需要的Scope添加到Assigned Client Scopes列表

4. 再次验证用户的Realm角色分配 #

确保测试用户确实被分配了Realm角色：

• 进入Users -> 选中你的测试用户 -> Role Mappings标签页，在Realm Roles区域，确认目标角色在Assigned Roles列表中

5. 重新获取Token #

所有配置修改后，需要让用户登出并重新获取Token，旧的Token不会自动应用新配置

调整完成后，新获取的JWT应该会包含roles字段，示例如下：

{
  "exp": 1669579902,
  "iat": 1669579602,
  // ... 其他字段
  "roles": ["admin", "user"],
  // ... 其他字段
}

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