Azure AD未在Id或Access Token中传递声明的问题排查求助

一、Azure AD端排查步骤 #

• 验证Manifest可选声明配置
  确认optionalClaims节点格式正确，需明确指定idToken和accessToken所需声明，示例配置：

  "optionalClaims": {
    "idToken": [
      {
        "name": "roles",
        "essential": false
      },
      {
        "name": "groups",
        "essential": false
      }
    ],
    "accessToken": [
      {
        "name": "roles",
        "essential": false
      }
    ]
  }
  

• 补全组声明专属配置
  仅靠Manifest无法自动返回组信息，需进入Azure AD应用注册的「Token configuration」页面，添加组声明：
  • 选择需包含的组类型（安全组/Office 365组）
  • 指定声明格式（如objectId或sAMAccountName）
• 确认API权限及管理员同意
  若需获取组/角色的完整信息，必须添加Directory.Read.All应用权限（非委托权限），并完成管理员同意步骤。

二、Keycloak端配置检查 #

• 启用JWT解析
  在Azure AD身份提供者的「Advanced」标签下，勾选「Use JWT from response」，确保Keycloak直接解析Azure返回的JWT令牌。
• 配置声明映射器
  进入身份提供者的「Mappers」标签，添加对应映射器实现同步：
  • 角色同步：添加「OIDC Role Importer」，设置Claim Name为roles，指定Keycloak的目标角色域。
  • 组同步：添加「OIDC Group Importer」，设置Claim Name为groups，可选择将Azure组ID映射为Keycloak组ID，或通过自定义转换逻辑匹配组名。
• 检查客户端范围
  在Keycloak对应客户端的「Client Scopes」标签中，确保已添加openid、profile等必要范围，若需自定义声明，需创建对应客户端范围并关联。

三、令牌请求参数验证 #

• 确认请求Scope
  前端调用/token端点时，必须携带包含所需权限的Scope参数，示例：openid profile roles，缺失对应Scope会导致Azure AD不返回可选声明。
• 直接测试Azure Token端点
  用Postman等工具直接请求Azure AD的token端点，获取令牌后用jwt.io解析：
  • 若令牌内无目标声明，问题锁定Azure AD端
  • 若令牌内有目标声明，问题出在Keycloak的解析或映射环节

四、额外排查要点 #

• 清除缓存：用无痕模式测试，避免浏览器旧令牌缓存干扰结果。
• 区分角色类型：Azure AD的应用角色（Manifest定义）和目录角色需分别配置声明，目录角色需在「Token configuration」单独添加。
• 应用类型验证：确保Azure AD应用注册为「Web」类型，SPA类型应用的令牌返回规则存在差异。

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