如何配置Keycloak身份代理显示Entra ID的ID Token声明

一、先确认 Entra ID 侧的基础配置（避免白忙活） #

你用Postman能拿到声明，这步可以快速核对：

• 确保Entra ID应用的ID Token配置里，roles、upn这些声明已经开启输出，且对应角色确实分配给了测试用户/组
• 检查应用的API权限，已经添加User.Read权限并完成管理员同意（保证用户属性能正常返回）

二、Keycloak 身份提供商的核心配置步骤 #

1. 进入身份提供商配置页 #

在Keycloak控制台里，打开目标Realm → 身份提供商 → 找到你配置的Entra ID OIDC提供商，点击编辑

2. 配置声明映射（重点搞定roles） #

切换到Mappers标签页，按以下步骤逐个添加映射：

（1）Roles 声明映射分两步

• 第一步：导入Entra ID的roles到Keycloak用户属性
  点击Create，选User Attribute Importer类型：
  • Name：随便起（比如entra-roles-import）
  • Claim JSON Path：$.roles（对应Entra ID ID Token里的roles字段，要是你Postman里的roles是嵌套路径，比如$.resource_access.xxx.roles，就改成对应路径）
  • User Attribute Name：entra_roles（自定义，后续要用到）
  • 勾选Add to ID token和Add to access token（按需选，要在哪个token里出现就勾哪个）
• 第二步：把导入的属性转为Keycloak内置角色
  再创建一个Role Importer类型的映射：
  • Name：比如map-entra-roles
  • Role Attribute Name：entra_roles（和上面的User Attribute Name完全一致）
  • Role Prefix：可选（比如加个ENTRA_，区分Keycloak本地角色）
  • 同样勾选要输出到的token类型

（2）UPN 声明映射

创建User Attribute Importer类型：

• Name：upn-mapper
• Claim JSON Path：$.upn
• User Attribute Name：upn
• 勾选输出选项，要是想把upn同步成Keycloak用户名，顺便勾上Sync user attributes

（3）Groups 声明映射

Entra ID的groups一般在$.groups字段（可能是组ID或组名，看你Entra ID的配置）：

• 先创建User Attribute Importer导入组：
  • Name：entra-groups-import
  • Claim JSON Path：$.groups
  • User Attribute Name：entra_groups
  • 勾选输出选项
• 要转成Keycloak组的话，再创建Group Importer类型：
  • Name：map-entra-groups
  • Group Attribute Name：entra_groups
  • Group Prefix：可选（比如ENTRA_GROUP_）

3. 调整身份提供商的高级设置 #

切回Settings标签页：

• 确保Client Authentication是开启状态（对应Entra ID应用的客户端密钥配置）
• 在Scopes字段里，添加openid、profile、roles这些Entra ID支持的范围
• 勾选Use JWT from response（让Keycloak直接用Entra ID返回的ID Token解析声明，避免二次处理丢数据）

三、验证配置是否生效 #

1. 从Keycloak发起登录，跳转到Entra ID完成认证
2. 拿Keycloak发的ID Token/Access Token，用jwt.io解析，看有没有roles、upn这些声明
3. 要是还没有，去Keycloak的Realm Settings → Tokens里，检查有没有限制声明输出的规则

常见坑排查 #

• 要是roles声明为空：确认Entra ID里用户确实被分配了该应用的角色，且角色在ID Token配置里已经开启
• 映射后声明名称不对：可以在映射的Claim Name字段自定义输出的名称（比如把entra_roles改成roles）
• 别忘了保存所有配置！有时候漏点保存白搭

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