Keycloak接入Azure AD OIDC身份提供商时IDP用户ID为随机UUID无法同步用户

1. 捕获Azure AD返回的授权响应内容 #

首先解决无法查看Azure AD返回数据的问题，有两种本地调试方式无需依赖第三方工具：

• 开启Keycloak事件调试：进入对应Realm的「事件」-「配置」，开启「保存事件」，事件类型勾选LOGIN、IDENTITY_PROVIDER_FIRST_LOGIN、IDENTITY_PROVIDER_POST_LOGIN，日志级别调整为DEBUG。复现登录流程后，在「事件」-「登录事件」列表即可查看完整的IdP返回字段明细。
• 开启OIDC协议日志：修改Keycloak启动参数，添加--log-level="org.keycloak.broker.oidc:DEBUG"，重启Keycloak后，控制台会打印完整的Azure AD返回的ID Token、Access Token以及用户信息端点的响应payload。

2. 修复身份提供商ID字段映射错误 #

你当前看到的随机UUID是Keycloak未匹配到指定的Azure AD用户唯一标识字段时，自动生成的临时值，并非Azure AD返回的字段，按以下步骤修正映射：

• 进入对应Realm的「身份提供商」，选择你配置的Azure AD OIDC实例，进入「映射器」标签页
• 删除默认的External ID映射规则，新建「用户属性映射器」，配置如下：
  • 同步模式：Force
  • 声明源属性名称：oid（Azure AD返回的用户全局唯一标识字段，可根据第一步捕获的实际返回字段调整）
  • 用户属性名称：brokerUserId
  • 存储在用户中：勾选
• 如果你希望用邮箱作为唯一匹配依据，也可以将声明源属性名称改为mail或upn字段。

3. 配置同邮箱用户自动匹配规则 #

无法匹配已有同邮箱用户是因为Keycloak默认没有开启邮箱关联逻辑，按以下步骤开启：

• 回到Azure AD身份提供商的配置页，进入「高级」设置板块
• 勾选「通过电子邮件找到已有用户」（低版本Keycloak对应选项为「关联已有用户」）
• 勾选「信任电子邮件」，跳过Keycloak侧的邮箱验证校验，直接匹配对应用户
• 根据你的需求选择同步策略：如果希望每次登录都用Azure AD的用户信息覆盖Keycloak的用户信息，勾选「更新配置文件每次登录」；如果仅首次登录同步，勾选「更新配置文件首次登录」即可。

额外注意事项 #

• 如果之前已经生成过错误的身份提供商关联记录，可以进入对应用户的「身份提供商关联」标签页，删除旧的Azure AD关联记录，重新登录即可生成正确的关联
• 测试时建议使用隐私模式窗口，避免本地缓存的登录状态影响测试结果

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