oauth2-proxy 对接 Azure ADazure 遗留 Provider应用注册全流程、V1/V2 端点配置与源码实现解析【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxyoauth2-proxy 内置了名为azure的身份提供商用于对接 Azure Active DirectoryAzure AD完成反向代理层的单点登录认证。本篇基于 7.10.x 版本文档完整还原从 Azure 门户注册应用、配置 Microsoft Graph 权限、创建客户端密钥到使用--providerazure配合 V1 或 V2.0 端点配置代理的全部实操步骤并结合 providers/azure.go 的源码实现解释--azure-tenant、--resource两个专属参数在登录、换票、会话校验各环节的真实行为。读完本文你可以独立完成该 Provider 的部署配置并理解 V1 与 V2 端点在 scope、resource 参数处理上的源码级差异。定位说明一个已进入弃用路径的遗留 Provider7.10.x 版本文档在 ms_azure_ad.md 开头明确标注azure是 Azure 的 legacy遗留且已弃用deprecated的提供商文档建议尽可能改用功能更完整的 Microsoft Entra ID Provider。两者在代码层都是独立的实现providers/azure.go 中的AzureProvider基于 Azure AD 端点V1/V2 OAuth 端点直接工作而 Entra ID Provider 则是完全遵循 OIDC 规范、支持组超额group overage与多租户应用的新一代实现。对于存量仍在使用--providerazure的部署本文的内容即为权威的运维参考。Provider 专属配置项azureProvider 在通用 OAuth 配置--provider、--client-id、--client-secret等之外只有两个专属配置项FlagToml 字段类型说明默认值--azure-tenantazure_tenantstring指定租户专属tenant-specific或通用common租户无关端点common--resourceresourcestring受保护的资源仅限 Azure AD空从源码结构可以确认这两个参数的定义位置命令行标志在 pkg/apis/options/legacy_options.go 中注册azure-tenant的默认值即common帮助文案与文档表格完全一致resource的帮助文案为 The resource that is protected (Azure AD only)。V2 配置结构体AzureOptions定义在 pkg/apis/options/providers.go其中包含Tenant默认common与GraphGroupField默认id用于从 Microsoft Graph 构建组列表时取用的字段。Provider 实例化入口在 providers/providers.go当--providerazure时调用NewAzureProvider并传入上述AzureConfig。第一步在 Azure 门户注册应用登录 Azure 门户选择Azure Active Directory进入App registrations点击New registration。填写应用名称选择支持的账户类型single-tenant、multi-tenant 等。在Redirect URI部分为每个受 oauth2-proxy 保护的应用创建一条Web平台回调地址例如https://internal.yourcompany.com/oauth2/callback然后点击Register。回调地址由 oauth2-proxy 的--redirect-url决定默认即外部访问地址/oauth2/callback需与门户中登记的 URI 精确一致否则换票时redirect_uri校验会失败——这一点可以从 providers/azure.go 的prepareRedeem中得到印证换票请求会把redirect_uri、client_id、client_secret、code、grant_typeauthorization_code以表单方式提交到 Redeem URL。第二步授予 Microsoft Graph 组读取权限在应用的API Permissions页面点击Add a permission选择Microsoft Graph再选择Application permissions点击Group并选择Group.Read.All点击Add permissions最后点击Grant admin consent这一步可能必须由租户管理员执行。文档在此处特别强调了一条生产环境常见坑位即使该权限在界面上显示 Admin consent requiredNo实际仍可能需要管理员同意——由于 AAD 中你无法看到的策略这种要求不会显式呈现。如果你登录时遇到 Need admin approval 报错最可能就是缺少这一步的权限授予。从源码看组信息正是依赖 Microsoft Graph 拉取的AzureProvider的 V2 端点路径会调用GET /v1.0/me/transitiveMemberOf见 providers/azure.go 的getMicrosoftGraphGroupsURL携带$counttrue$filtersecurityEnabledeqtrue过滤条件只选取安全组并以ConsistencyLevel: eventual请求头 Bearer 访问令牌分页读取odata.nextLink全部组取组名时使用的字段由GraphGroupField决定默认id可选displayName。没有 Group.Read.All 权限这条链路在组超过 ID token 携带能力时就会取不到数据。第三步仅 V2.0 端点设置 accessTokenAcceptedVersion如果计划使用 v2.0 Azure Auth 端点Microsoft Identity Platform 端点需进入应用的Manifest页面在应用清单中设置accessTokenAcceptedVersion: 2。该设置控制 AAD 签发的访问令牌版本与 V2.0 端点的 JWT 校验体系配套。第四步创建客户端密钥在应用的Certificates secrets页面添加一条新的 client secret并在点击Add之后立即记下密钥值此后只能看到掩码无法再次完整查看。该值将填入--client-secret。oauth2-proxy 代理配置V1 与 V2 端点V1 Azure Auth 端点对应 Azure Active Directory 端点https://login.microsoftonline.com/common/oauth2/authorize配置示例--providerazure --client-id应用注册时的 application ID --client-secret第四步创建的客户端密钥值 --azure-tenant{tenant-id} --oidc-issuer-urlhttps://sts.windows.net/{tenant-id}/注意这里--oidc-issuer-url指向的是sts.windows.net/{tenant-id}/——启用该选项后oauth2-proxy 会通过 OIDC verifier 校验令牌签名与签发方这正是--resource参数生效的前提之一。V2 Azure Auth 端点对应 Microsoft Identity Platform 端点https://login.microsoftonline.com/common/oauth2/v2.0/authorize配置示例--providerazure --client-id应用注册时的 application ID --client-secret第四步创建的客户端密钥值 --azure-tenant{tenant-id} --oidc-issuer-urlhttps://login.microsoftonline.com/{tenant-id}/v2.0两个示例中--client-id对应 Azure 门户应用注册信息里的Application (client) ID--azure-tenant填入租户 ID 或域名以将端点从common切换为租户专属端点。源码解读两个端点为何行为不同providers/azure.go 的NewAzureProvider揭示了 V1/V2 的分野机制端点默认值未显式指定时Login URL 为https://login.microsoftonline.com/common/oauth2/authorize、Redeem URL 为https://login.microsoftonline.com/common/oauth2/token、Profile URL 为https://graph.microsoft.com/v1.0/meproviders/azure.go。租户替换当--azure-tenant非空且未被其他设置覆盖时overrideTenantURL会把路径重写为/{tenant}/oauth2/authorize与/{tenant}/oauth2/token即从common端点切到租户专属端点。V2 判定只要最终 Login URL 中包含字符串v2.0isV2Endpoint即被置为true并触发一串针对 V2 协议的适配自动向 scope 追加https://graph.microsoft.com/.defaultV2 中访问 Microsoft Graph 必须使用该默认 scopeV1 的groupsscope 在 V2 下不被接受源码会检测并自动剔除同时打印 WARNING若同时配置了--resource直接打印警告--resourceoption has no effect when using the Azure OAuth V2 endpoint。登录 URL 构造GetLoginURLproviders/azure.go中只有当resource非空且不是 V2 端点时才会把resource作为额外参数加入授权请求prepareRedeem换票逻辑与此完全一致。这与 V1 resources 与 V2 scopes 的模型差异相符。providers/azure_test.go 中的TestAzureProviderProtectedResourceConfiguredOAuthV1与TestAzureProviderProtectedResourceConfiguredOAuthV2两个用例分别固化了上述两种行为可作为回归验证依据。--resource参数的实操注意事项V2 端点 --resource时的/.default写法文档 Notes 指出当把 v2.0 端点https://login.microsoftonline.com/{tenant-id}/v2.0用作--oidc-issuer-url并同时使用--resource时务必在资源名末尾追加/.default可参考微软官方 v2-permissions-and-consent 文档中 The default scope 一节的说明。源码层面的更严格事实从 providers/azure.go 的实现看只要登录 URL 命中 V2 端点--resource根本不会出现在登录请求或换票参数中仅产生 WARNING 日志。也就是说--resource的实质作用域是V1 端点在授权请求与 token 请求中以resource参数传递见GetLoginURL与prepareRedeem与 V2 端点混用时应以上述/.default写法或改用 scope 表达为准。实用提示nginx 下 Cookie 过大的问题文档 Notes 的第二条记录了与 Azure 提供商相关的经典运维问题当 oauth2-proxy 与 nginx 配合、使用 cookie 会话存储时可能发现会话 cookie 过大而无法被正确透传。文档给出的两种解决途径调大 nginx 的proxy_buffer_size改用 Redis 会话存储——即 sessions.md 中的 Redis Storage 方案通过--session-store-typeredis与--redis-connection-url将会话以加密形式存入 Rediscookie 中只保留 ticket 句柄从根本上解决体积问题。认证主链路的源码验证理解上述配置为何有效需要看到azureProvider 的完整调用链均位于 providers/azure.go换票RedeemRedeem以application/x-www-form-urlencodedPOST 到 Redeem URL解析access_token、refresh_token、id_token与expires_on按字符串解析后转为 Unix 时间戳作为会话过期时间随后进入 claim 提取。令牌校验与 claim 提取extractClaimsIntoSession先通过verifySessionToken校验令牌——若配置了 OIDC verifier即设置了--oidc-issuer-url优先校验id_token失败则回退校验access_tokenclaim 解析同样采用 先 id_token、失败回退 access_token 的容错策略源码注释指出这是针对 AAD 在某些情况下未对 id_token 签名的已知问题。会话增强EnrichSession令牌中取不到邮箱时回落到 Profile API/v1.0/me依次尝试mail、otherMails、userPrincipalName三个字段提取邮箱V2 端点下还会调用 Microsoft GraphtransitiveMemberOf补齐组列表并去重。会话校验ValidateSession每次请求时用validateToken以 Bearer 头携带访问令牌访问 Validate URL默认复用 Profile URL确认令牌仍然有效。刷新RefreshSession凭refresh_token再次调用 Redeem URL 换取新的 access/id 令牌并重新提取 claims。小结azureProvider 提供了接入 Azure AD 的最短路径门户侧完成应用注册、Group.Read.All管理员同意必要时配合accessTokenAcceptedVersion2代理侧只需--providerazure client 凭据 --azure-tenant再按 V1sts.windows.net发行方或 V2login.microsoftonline.com/{tenant-id}/v2.0发行方选择对应的--oidc-issuer-url即可。--resource仅对 V1 端点有效--azure-tenant控制端点是租户专属还是common。需要再次强调该 Provider 已被标记为 deprecated新部署建议直接使用 Microsoft Entra ID Provider存量azure部署在进行版本升级或排障时本文的源码行为说明scope 自动改写、resource忽略警告、Graph 组拉取链路均可作为定位依据。【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考