Protocol Mapper中“Role name Mapper”的含义及配置方法咨询

一、核心作用 #

• 将Keycloak中用户关联的角色信息，映射到OAuth2/OIDC协议的令牌（ID Token、Access Token）或UserInfo响应中，让依赖这些令牌的下游服务可以直接读取角色权限，无需额外调用Keycloak的角色查询接口。
• 支持自定义角色过滤规则、令牌中的角色字段名，适配不同服务的权限校验逻辑，比如只同步特定前缀的角色，或者将角色字段命名为符合业务习惯的名称。

二、配置步骤（基于提供的截图界面） #

1. 基础信息配置

   • 填写Name：给该映射器设置一个辨识度高的名称，比如User Role Mapper
   • 选择Mapper Type：固定选择Role name Mapper
   • 设置Token Claim Name：定义角色在令牌中存储的字段名，比如roles或user_roles，下游服务将通过这个字段获取角色信息
   • 选择Claim JSON Type：若用户存在多个角色，建议选JSON（以数组形式返回）；单个角色可选String

2. 角色范围与输出控制

   • Role prefix：可选配置，仅保留带有指定前缀的角色，例如填写ROLE_后，只有以ROLE_开头的角色会被加入令牌
   • 勾选Add to ID token：角色信息将被写入ID Token
   • 勾选Add to access token：角色信息将被写入Access Token
   • 勾选Add to userinfo：调用UserInfo接口时会返回角色信息
   • Single role attribute：若用户仅拥有单个角色，勾选后角色将以字符串形式返回；未勾选则始终以数组形式返回

3. 完成配置
   确认所有配置项后，点击保存按钮即可生效。

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