KeyCloak：如何将角色属性添加到用户JWT（Access Token）中？

这不是Keycloak的设计限制，而是你使用了错误的映射器类型，导致角色属性无法注入到Access Token中。组属性能正常生效，是因为你大概率用了对应的Group Attribute映射器，而角色属性需要专门的Role Attribute映射器来处理。

正确操作步骤 #

1. 确认角色属性配置

   • 进入Keycloak后台，打开目标Realm → Roles → 找到Manager角色 → 切换到Attributes标签，确认Actions属性已添加且值正确。

2. 创建Role Attribute映射器

   • 打开你的Actions Client Scope → 切换到Mappers标签 → 点击Add Mapper
   • 在弹出界面中，选择By configuration下的Role Attribute选项
   • 配置映射器参数：
     • Name：自定义名称（如Role-Actions-Mapper）
     • Role Attribute Name：填写角色中设置的属性名Actions
     • Token Claim Name：设置JWT中要显示的字段名（如actions）
     • Claim JSON Type：根据属性值类型选择（如String或JSON）
     • 勾选Add to access token
     • 其余选项保持默认，点击Save

3. 验证客户端Scope关联

   • 打开你的API客户端 → 切换到Client Scopes标签 → 确认Actions已在Default Client Scopes列表中，且未被添加到Optional Client Scopes或排除列表。

4. 生成新令牌验证

   • 注销当前用户会话，重新获取Access Token，用jwt.io解析令牌，检查是否包含actions字段。

额外排查点 #

• 清理Keycloak缓存：如果之前生成过令牌，Keycloak可能缓存旧内容，可重启服务或在Realm设置中清除用户会话。
• 检查角色分配：确认目标用户确实被分配了Manager角色，且角色未被禁用。
• 检查客户端配置：确保API客户端的Access Token Lifespan配置正常，且未在Fine Grain OpenID Connect Configuration中限制相关Claim的生成。

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