如何通过Keycloak映射器添加属性并在Token中显示？外部IDP映射后JWT无变化

• 确认映射器配置位置
  要确保映射器是添加在外部身份提供商的配置页面的「映射器」标签下，而非客户端的映射器列表。客户端映射器负责Keycloak内部用户属性到Token的转换，而外部IDP映射器的作用是将外部IDP返回的属性同步到Keycloak用户对象中。

• 核对映射器类型与参数

  • 若使用「Attribute Importer」类型：确认外部IDP返回的属性名与映射器中填写的「Attribute Name」完全匹配（注意大小写敏感），同时「User Attribute Name」要填写你希望存储到Keycloak用户的属性标识；
  • 若使用「Hardcoded Attribute」类型：检查「Attribute Value」是否正确填写，「User Attribute Name」无拼写错误；
  • 将映射器的「Sync Mode Override」设置为Force或Overwrite，避免旧属性覆盖新同步内容。

• 验证外部IDP是否返回目标属性
  开启Keycloak调试日志，将org.keycloak.broker的日志级别设为DEBUG，重新触发登录流程后查看日志，确认外部IDP返回的用户信息中包含你要映射的属性。若IDP未返回该属性，映射器自然无法生效。

• 确保客户端能访问同步后的属性

  • 在客户端的「范围」标签页中，将目标用户属性添加到客户端默认范围；或在客户端映射器中新增「User Attribute」类型映射器，把同步后的用户属性映射到JWT的claim中；
  • 检查客户端的「Access Type」是否为confidential或public，若未开启「Full Scope Allowed」，需手动添加所需属性范围。

• 清除缓存并重新登录
  Keycloak会缓存用户会话信息，修改配置后需在管理控制台的用户页面找到测试用户，点击「注销所有会话」，再重新登录获取新Token；必要时可重启Keycloak服务确保配置完全生效。

• 仔细解码核对Token内容
  使用本地JWT解码工具（避免使用在线工具泄露敏感信息）解码生成的Token，检查目标属性是否存在于realm_access、resource_access或顶层claim中，不要遗漏嵌套结构。

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