使用AzureAD认证时JWT令牌缺失roles claim问题（基于oauth2-proxy）

第一步：AzureAD应用配置排查 #

• 确认AzureAD应用注册的清单配置中，accessTokenAcceptedVersion参数是否设置为2，默认值null对应v1版本令牌，v1令牌的roles声明默认仅存于id_token中，不会放入access_token
• 检查你创建的App角色是否已经分配给当前登录的用户/服务主体，未分配的角色不会出现在返回令牌中
• 进入应用注册的API权限页，确认你已经添加了对应自定义角色的权限，且完成了管理员同意，未授权的权限不会被包含在令牌返回字段
• 进入令牌配置页，添加可选声明：选择access_token类型，勾选roles声明，强制AzureAD返回该字段
• 如果你的roles是从AzureAD用户组映射而来，需要在应用清单中设置groupMembershipClaims为All或SecurityGroup，同时配置可选声明将组ID/名称映射到roles字段

第二步：oauth2-proxy启动参数排查 #

• 确认--provider参数是否设置为azure，使用通用oidc provider会丢失AzureAD特有的配置适配，无法正确解析部分声明
• 检查是否配置了--oidc-extra-audience参数，如果你的令牌受众和oauth2-proxy配置的client-id不匹配，会导致部分声明被过滤
• 确认--scope参数是否包含自定义角色对应的作用域，默认仅请求openid email profile不会返回角色相关字段，需要额外添加自定义API作用域，比如api://<你的应用client-id>/.default
• 如果你需要从id_token而非access_token中提取roles，需要添加参数--user-id-claim=roles，或根据业务需求配置--oidc-email-claim=roles调整声明映射规则
• 检查是否配置了--set-authorization-header=true，该参数开启后oauth2-proxy才会把携带完整声明的JWT放入Authorization请求头传递给上游服务
• 确认已经添加--pass-access-token=true或--pass-id-token=true参数，确保对应令牌会被oauth2-proxy透传

第三步：令牌内容验证 #

• 手动走授权流程获取返回的access_token/id_token，本地解码确认AzureAD侧是否真的返回了roles字段，如果解码后不存在该字段，说明问题出在AzureAD配置侧，和oauth2-proxy无关
• 如果令牌本身包含roles字段，但oauth2-proxy传递给上游时丢失，检查是否配置了--extra-jwt-issuers参数，正确匹配令牌的issuer和audience让oauth2-proxy可以识别并解析自定义声明
• 注意oauth2-proxy默认会过滤非标准的自定义声明，你可以通过--session-cookie-minimal=false参数关闭会话cookie精简模式，避免自定义声明被过滤

常见踩坑提示 #

AzureAD v1和v2令牌的声明规则差异很大，v1令牌的roles默认仅存在于id_token中，v2令牌可以配置同时出现在access_token和id_token里，不要直接复用v1的配置逻辑到v2授权流程
如果你配置的是应用权限而非委托权限，roles只会出现在客户端凭证流程获取的令牌里，用户登录的授权码流程不会返回应用级别的roles声明

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