oauth2-proxy 集成 Azure AD 实战指南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-proxy本篇技术指南以 oauth2-proxy 官方文档中 Azure 提供方Azure provider章节为核心完整讲解如何通过 oauth2-proxy 为内网应用接入 Azure Active Directory 身份认证。读完本文你将掌握在 Azure 门户中注册应用、授予 Microsoft Graph 组读取权限、生成客户端密钥的完整流程并能分别基于 Azure AD V1 端点与 Microsoft Identity Platform V2 端点正确配置--azure-tenant、--resource、--oidc-issuer-url等核心参数理解 oauth2-proxy 在源码层面对两种端点的差异化处理逻辑。一、Azure 提供方概览与核心配置项在 oauth2-proxy 中Azure 是一个内置的 OAuth2/OIDC 提供方provider其实现位于 providers/azure.go。与通用 OIDC 提供方不同Azure 提供方在源码中预置了三组默认端点 URL默认登录端点Login URLhttps://login.microsoftonline.com/common/oauth2/authorize默认令牌兑换端点Redeem URLhttps://login.microsoftonline.com/common/oauth2/token默认用户资料端点Profile URLhttps://graph.microsoft.com/v1.0/me。当你指定--providerazure时NewAzureProvider 会以默认 Scopeopenid初始化提供方并根据后续配置自动调整端点与 Scope。根据官方文档Azure 提供方有两个专属配置项同时配合一个通用配置项使用Flag命令行Toml 字段Type说明默认值--azure-tenantazure_tenantstring跳转到租户专属tenant-specific或公共tenant-independent即common的端点common--resourceresourcestring受保护资源仅 Azure AD 生效空其中--resource在源码中对应 ProviderOptions.ProtectedResource 字段注释明确标注resource that is protected (Azure AD and ADFS only)即该参数只对 Azure AD 与 ADFS 两类提供方生效对其他提供方无意义。1.1--azure-tenant参数详解从源码 legacy_options.go 可以看到该参数的完整定义--azure-tenant, 默认值 common含义go to a tenant-specific or common (tenant-independent) endpoint.其作用机制在 NewAzureProvider 中体现得十分直观当opts.Tenant非空时提供方会调用overrideTenantURL将登录端点与令牌兑换端点改写为https://login.microsoftonline.com/{tenant}/oauth2/authorize与https://login.microsoftonline.com/{tenant}/oauth2/token的形态见 overrideTenantURL。也就是说不设置默认common走租户无关的公共端点适合多租户场景设置具体租户 ID走租户专属端点令牌签发与校验都限定在该租户内安全性更高。需要特别说明的是在 7.7.x 版本对应的 legacy_options.go 中还存在--azure-graph-group-field参数源码中对应AzureGraphGroupField配置结构体见 AzureOptions.GraphGroupField它用于配置从 Microsoft Graph 构建组列表时使用的组字段id或displayName默认id仅在 v2.0 OIDC 端点下可用该参数在文档表格中未列出但在使用组授权--allowed-group时会影响匹配依据值得留意。二、Azure 门户端应用注册与权限授予2.1 注册应用App Registration打开 https://portal.azure.com选择Azure Active Directory进入App registrations点击New registration。为应用取一个名字勾选支持的账户类型single-tenant、multi-tenant 等。在Redirect URI区域为每个需要通过 oauth2-proxy 保护的应用新建一条Web平台条目回调地址形如https://internal.yourcompany.com/oauth2/callback即 oauth2-proxy 默认的回调路径/oauth2/callback然后点击Register完成注册。2.2 添加组读取权限关键步骤为了让 oauth2-proxy 能够通过--allowed-group实现基于组的访问控制需要为应用注册添加 Microsoft Graph 的组读取权限在应用的API Permissions页面点击Add a permission选择Microsoft Graph→Application permissions→Group→ 勾选Group.Read.All点击Add permissions然后执行Grant admin consent该操作可能需要管理员账号完成。IMPORTANT即使该权限在门户中被标注为Admin consent requiredNo由于 AAD 中存在你无法直接看到的策略管理员同意admin consent实际上仍可能是必需的。如果在登录时遇到Need admin approval错误大概率就是因为缺少这一步管理员授权。2.3 开启 V2.0 令牌可选仅在用 V2 端点时如果你计划使用 Azure Auth v2.0 端点Microsoft Identity Platform需要进入应用注册的Manifest页面在 App registration manifest 文件中将accessTokenAcceptedVersion设置为2accessTokenAcceptedVersion: 22.4 生成客户端密钥在应用的Certificates secrets页面新增一个 client secret点击Add之后立即记录下生成的密钥值之后不再可查看完整值。该值将作为--client-secret使用。三、oauth2-proxy 侧两套端点配置命令官方文档提供了两种启动配置分别对应 Azure 的两代认证端点。两种方式的共同点都是--providerazure--client-id--client-secret--azure-tenant{tenant-id}差异仅在--oidc-issuer-url指向不同的发行方地址。3.1 V1 端点Azure Active Directory EndpointsV1 端点对应授权地址https://login.microsoftonline.com/common/oauth2/authorize配置命令如下--providerazure --client-idapplication ID from step 3 --client-secretvalue from step 5 --azure-tenant{tenant-id} --oidc-issuer-urlhttps://sts.windows.net/{tenant-id}/V1 模式的核心特征令牌发行方issuer固定为https://sts.windows.net/{tenant-id}/支持通过--resource指定受保护资源资源会以resource参数的形式加入登录请求与令牌兑换请求见 GetLoginURL 与 prepareRedeem 中if p.ProtectedResource ! nil ... !p.isV2Endpoint的条件分支测试 TestAzureProviderProtectedResourceConfiguredOAuthV1 验证了 V1 下登录 URL 会携带resourcehttp%3A%2F%2Fmy.resource.test这样的查询参数。3.2 V2 端点Microsoft Identity Platform EndpointsV2 端点对应授权地址https://login.microsoftonline.com/common/oauth2/v2.0/authorize配置命令如下--providerazure --client-idapplication ID from step 3 --client-secretvalue from step 5 --azure-tenant{tenant-id} --oidc-issuer-urlhttps://login.microsoftonline.com/{tenant-id}/v2.0V2 模式的核心特征令牌发行方为https://login.microsoftonline.com/{tenant-id}/v2.0--resource参数在 V2 端点下不再生效源码 NewAzureProvider 会通过检测 Login URL 中是否包含v2.0来判定isV2Endpoint一旦判定为 V2会自动向 Scope 追加https://graph.microsoft.com/.default同时打印警告--resourceoption has no effect when using the Azure OAuth V2 endpoint并在 GetLoginURL 与 prepareRedeem 中跳过resource参数。测试 TestAzureProviderProtectedResourceConfiguredOAuthV2 验证了 V2 下登录 URL 既不包含resource查询参数、也不会把资源名塞进 scopeV2 下若配置了--allowed-group等组校验需求oauth2-proxy 还会在会话富化阶段调用 Microsoft Graph 的https://graph.microsoft.com/v1.0/me/transitiveMemberOf接口拉取安全组见 getMicrosoftGraphGroupsURL 与 getGroupsFromProfileAPI该接口请求会附带ConsistencyLevel: eventual头并自动处理odata.nextLink分页由于 V1 与 V2 的令牌格式、Scope 语义存在差异两种配置的--oidc-issuer-url绝不能混用否则 OIDC 发行方校验会失败。3.3--resource与/.default的注意事项官方文档特别强调当使用 v2.0 端点https://login.microsoftonline.com/{tenant-id}/v2.0作为--oidc-issuer-url且同时配合--resource使用时必须在资源名末尾追加/.default关于 V2 的.defaultScope 语义可参考微软官方文档《v2-permissions-and-consent》中the default scope一节。例如资源名写作https://management.azure.com/.default。不过如前所述源码层面 V2 模式下--resource实际上不会进入请求参数因此更稳妥的做法是 V2 模式下直接依赖自动追加的https://graph.microsoft.com/.defaultScope而不去手动设置--resource。四、常见问题与排错4.1 登录报 Need admin approval这通常不是因为 Group.Read.All 权限在门户中标注为无需同意就真的免同意而是 AAD 租户策略导致的隐性管理员同意要求。解决方式回到应用注册的API Permissions页面对 Microsoft Graph 权限执行Grant admin consent。4.2 nginx 环境下 Cookie 过大官方文档明确指出当 Azure 认证提供方与 nginx、cookie 会话存储cookie session store配合使用时可能因 Cookie 过大而无法被正确透传。解决办法有两种调大 nginx 的proxy_buffer_size改用 Redis 会话存储将会话从 Cookie 中迁移到 Redis 服务端从根本上解决体积限制问题。4.3 登录授权码兑换失败从源码看Redeem 会以application/x-www-form-urlencoded向令牌端点 POSTcode、client_id、client_secret、redirect_uri、grant_typeauthorization_code等参数并盲目地同时尝试 JSON 与表单两种响应格式解析。若兑换失败请检查回调地址是否与门户中注册的 Redirect URI 完全一致含协议与路径、client secret 是否正确、以及--azure-tenant是否与令牌发行租户匹配。4.4 会话刷新Azure 提供方实现了 RefreshSession当会话携带 refresh token 时会通过 redeemRefreshToken 向令牌端点换取新的 access token、id token 与 refresh token并重新解析 email 与 groups 声明expires_on字段按字符串格式解析。这要求应用注册时正确开放 offline_access 相关的刷新令牌能力。五、Alpha 配置结构化 YAML下的对应写法除了命令行与 TOML 配置oauth2-proxy 还提供 alpha 结构化配置--alpha-configAzure 提供方在其中的对应结构为azureConfig类型AzureOptions见 alpha_config.md包含两个字段见 alpha_config.mdFieldType说明默认值tenantstring跳转到租户专属或公共common端点commongraphGroupFieldstring从 Microsoft Graph 构建组列表时使用的组字段idAlpha 配置下的 Azure 提供方示例敏感值支持${ENV_VAR}环境变量注入见 alpha_config.mdproviders: - provider: azure clientID: ${AZURE_CLIENT_ID} clientSecret: ${AZURE_CLIENT_SECRET} azureConfig: tenant: {tenant-id} graphGroupField: id该结构定义位于 alpha_options.goProviders字段底层数据类型AzureOptions见 providers.go与命令行参数一一对应。六、小结将 oauth2-proxy 接入 Azure AD 的完整链路可以概括为四步在 Azure 门户注册应用并登记回调地址 → 授予 Group.Read.All 应用权限并完成管理员同意 → 生成客户端密钥 → 按 V1 或 V2 端点选择对应的--oidc-issuer-url组合启动 oauth2-proxy。两者的关键差异在于V1 使用sts.windows.net发行方并支持--resource资源参数V2 使用login.microsoftonline.com/{tenant}/v2.0发行方、自动追加/.default图 Scope 且忽略--resource。结合 providers/azure.go 的源码实现与 providers/azure_test.go 的测试用例可以对端点选择、租户改写、Scope 追加等内部行为获得确定性的理解从而在排查登录失败、Cookie 过大等问题时有的放矢。【免费下载链接】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），仅供参考
oauth2-proxy 集成 Azure AD 实战指南：V1/V2 端点配置、租户与资源参数全解析
oauth2-proxy 集成 Azure AD 实战指南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-proxy本篇技术指南以 oauth2-proxy 官方文档中 Azure 提供方Azure provider章节为核心完整讲解如何通过 oauth2-proxy 为内网应用接入 Azure Active Directory 身份认证。读完本文你将掌握在 Azure 门户中注册应用、授予 Microsoft Graph 组读取权限、生成客户端密钥的完整流程并能分别基于 Azure AD V1 端点与 Microsoft Identity Platform V2 端点正确配置--azure-tenant、--resource、--oidc-issuer-url等核心参数理解 oauth2-proxy 在源码层面对两种端点的差异化处理逻辑。一、Azure 提供方概览与核心配置项在 oauth2-proxy 中Azure 是一个内置的 OAuth2/OIDC 提供方provider其实现位于 providers/azure.go。与通用 OIDC 提供方不同Azure 提供方在源码中预置了三组默认端点 URL默认登录端点Login URLhttps://login.microsoftonline.com/common/oauth2/authorize默认令牌兑换端点Redeem URLhttps://login.microsoftonline.com/common/oauth2/token默认用户资料端点Profile URLhttps://graph.microsoft.com/v1.0/me。当你指定--providerazure时NewAzureProvider 会以默认 Scopeopenid初始化提供方并根据后续配置自动调整端点与 Scope。根据官方文档Azure 提供方有两个专属配置项同时配合一个通用配置项使用Flag命令行Toml 字段Type说明默认值--azure-tenantazure_tenantstring跳转到租户专属tenant-specific或公共tenant-independent即common的端点common--resourceresourcestring受保护资源仅 Azure AD 生效空其中--resource在源码中对应 ProviderOptions.ProtectedResource 字段注释明确标注resource that is protected (Azure AD and ADFS only)即该参数只对 Azure AD 与 ADFS 两类提供方生效对其他提供方无意义。1.1--azure-tenant参数详解从源码 legacy_options.go 可以看到该参数的完整定义--azure-tenant, 默认值 common含义go to a tenant-specific or common (tenant-independent) endpoint.其作用机制在 NewAzureProvider 中体现得十分直观当opts.Tenant非空时提供方会调用overrideTenantURL将登录端点与令牌兑换端点改写为https://login.microsoftonline.com/{tenant}/oauth2/authorize与https://login.microsoftonline.com/{tenant}/oauth2/token的形态见 overrideTenantURL。也就是说不设置默认common走租户无关的公共端点适合多租户场景设置具体租户 ID走租户专属端点令牌签发与校验都限定在该租户内安全性更高。需要特别说明的是在 7.7.x 版本对应的 legacy_options.go 中还存在--azure-graph-group-field参数源码中对应AzureGraphGroupField配置结构体见 AzureOptions.GraphGroupField它用于配置从 Microsoft Graph 构建组列表时使用的组字段id或displayName默认id仅在 v2.0 OIDC 端点下可用该参数在文档表格中未列出但在使用组授权--allowed-group时会影响匹配依据值得留意。二、Azure 门户端应用注册与权限授予2.1 注册应用App Registration打开 https://portal.azure.com选择Azure Active Directory进入App registrations点击New registration。为应用取一个名字勾选支持的账户类型single-tenant、multi-tenant 等。在Redirect URI区域为每个需要通过 oauth2-proxy 保护的应用新建一条Web平台条目回调地址形如https://internal.yourcompany.com/oauth2/callback即 oauth2-proxy 默认的回调路径/oauth2/callback然后点击Register完成注册。2.2 添加组读取权限关键步骤为了让 oauth2-proxy 能够通过--allowed-group实现基于组的访问控制需要为应用注册添加 Microsoft Graph 的组读取权限在应用的API Permissions页面点击Add a permission选择Microsoft Graph→Application permissions→Group→ 勾选Group.Read.All点击Add permissions然后执行Grant admin consent该操作可能需要管理员账号完成。IMPORTANT即使该权限在门户中被标注为Admin consent requiredNo由于 AAD 中存在你无法直接看到的策略管理员同意admin consent实际上仍可能是必需的。如果在登录时遇到Need admin approval错误大概率就是因为缺少这一步管理员授权。2.3 开启 V2.0 令牌可选仅在用 V2 端点时如果你计划使用 Azure Auth v2.0 端点Microsoft Identity Platform需要进入应用注册的Manifest页面在 App registration manifest 文件中将accessTokenAcceptedVersion设置为2accessTokenAcceptedVersion: 22.4 生成客户端密钥在应用的Certificates secrets页面新增一个 client secret点击Add之后立即记录下生成的密钥值之后不再可查看完整值。该值将作为--client-secret使用。三、oauth2-proxy 侧两套端点配置命令官方文档提供了两种启动配置分别对应 Azure 的两代认证端点。两种方式的共同点都是--providerazure--client-id--client-secret--azure-tenant{tenant-id}差异仅在--oidc-issuer-url指向不同的发行方地址。3.1 V1 端点Azure Active Directory EndpointsV1 端点对应授权地址https://login.microsoftonline.com/common/oauth2/authorize配置命令如下--providerazure --client-idapplication ID from step 3 --client-secretvalue from step 5 --azure-tenant{tenant-id} --oidc-issuer-urlhttps://sts.windows.net/{tenant-id}/V1 模式的核心特征令牌发行方issuer固定为https://sts.windows.net/{tenant-id}/支持通过--resource指定受保护资源资源会以resource参数的形式加入登录请求与令牌兑换请求见 GetLoginURL 与 prepareRedeem 中if p.ProtectedResource ! nil ... !p.isV2Endpoint的条件分支测试 TestAzureProviderProtectedResourceConfiguredOAuthV1 验证了 V1 下登录 URL 会携带resourcehttp%3A%2F%2Fmy.resource.test这样的查询参数。3.2 V2 端点Microsoft Identity Platform EndpointsV2 端点对应授权地址https://login.microsoftonline.com/common/oauth2/v2.0/authorize配置命令如下--providerazure --client-idapplication ID from step 3 --client-secretvalue from step 5 --azure-tenant{tenant-id} --oidc-issuer-urlhttps://login.microsoftonline.com/{tenant-id}/v2.0V2 模式的核心特征令牌发行方为https://login.microsoftonline.com/{tenant-id}/v2.0--resource参数在 V2 端点下不再生效源码 NewAzureProvider 会通过检测 Login URL 中是否包含v2.0来判定isV2Endpoint一旦判定为 V2会自动向 Scope 追加https://graph.microsoft.com/.default同时打印警告--resourceoption has no effect when using the Azure OAuth V2 endpoint并在 GetLoginURL 与 prepareRedeem 中跳过resource参数。测试 TestAzureProviderProtectedResourceConfiguredOAuthV2 验证了 V2 下登录 URL 既不包含resource查询参数、也不会把资源名塞进 scopeV2 下若配置了--allowed-group等组校验需求oauth2-proxy 还会在会话富化阶段调用 Microsoft Graph 的https://graph.microsoft.com/v1.0/me/transitiveMemberOf接口拉取安全组见 getMicrosoftGraphGroupsURL 与 getGroupsFromProfileAPI该接口请求会附带ConsistencyLevel: eventual头并自动处理odata.nextLink分页由于 V1 与 V2 的令牌格式、Scope 语义存在差异两种配置的--oidc-issuer-url绝不能混用否则 OIDC 发行方校验会失败。3.3--resource与/.default的注意事项官方文档特别强调当使用 v2.0 端点https://login.microsoftonline.com/{tenant-id}/v2.0作为--oidc-issuer-url且同时配合--resource使用时必须在资源名末尾追加/.default关于 V2 的.defaultScope 语义可参考微软官方文档《v2-permissions-and-consent》中the default scope一节。例如资源名写作https://management.azure.com/.default。不过如前所述源码层面 V2 模式下--resource实际上不会进入请求参数因此更稳妥的做法是 V2 模式下直接依赖自动追加的https://graph.microsoft.com/.defaultScope而不去手动设置--resource。四、常见问题与排错4.1 登录报 Need admin approval这通常不是因为 Group.Read.All 权限在门户中标注为无需同意就真的免同意而是 AAD 租户策略导致的隐性管理员同意要求。解决方式回到应用注册的API Permissions页面对 Microsoft Graph 权限执行Grant admin consent。4.2 nginx 环境下 Cookie 过大官方文档明确指出当 Azure 认证提供方与 nginx、cookie 会话存储cookie session store配合使用时可能因 Cookie 过大而无法被正确透传。解决办法有两种调大 nginx 的proxy_buffer_size改用 Redis 会话存储将会话从 Cookie 中迁移到 Redis 服务端从根本上解决体积限制问题。4.3 登录授权码兑换失败从源码看Redeem 会以application/x-www-form-urlencoded向令牌端点 POSTcode、client_id、client_secret、redirect_uri、grant_typeauthorization_code等参数并盲目地同时尝试 JSON 与表单两种响应格式解析。若兑换失败请检查回调地址是否与门户中注册的 Redirect URI 完全一致含协议与路径、client secret 是否正确、以及--azure-tenant是否与令牌发行租户匹配。4.4 会话刷新Azure 提供方实现了 RefreshSession当会话携带 refresh token 时会通过 redeemRefreshToken 向令牌端点换取新的 access token、id token 与 refresh token并重新解析 email 与 groups 声明expires_on字段按字符串格式解析。这要求应用注册时正确开放 offline_access 相关的刷新令牌能力。五、Alpha 配置结构化 YAML下的对应写法除了命令行与 TOML 配置oauth2-proxy 还提供 alpha 结构化配置--alpha-configAzure 提供方在其中的对应结构为azureConfig类型AzureOptions见 alpha_config.md包含两个字段见 alpha_config.mdFieldType说明默认值tenantstring跳转到租户专属或公共common端点commongraphGroupFieldstring从 Microsoft Graph 构建组列表时使用的组字段idAlpha 配置下的 Azure 提供方示例敏感值支持${ENV_VAR}环境变量注入见 alpha_config.mdproviders: - provider: azure clientID: ${AZURE_CLIENT_ID} clientSecret: ${AZURE_CLIENT_SECRET} azureConfig: tenant: {tenant-id} graphGroupField: id该结构定义位于 alpha_options.goProviders字段底层数据类型AzureOptions见 providers.go与命令行参数一一对应。六、小结将 oauth2-proxy 接入 Azure AD 的完整链路可以概括为四步在 Azure 门户注册应用并登记回调地址 → 授予 Group.Read.All 应用权限并完成管理员同意 → 生成客户端密钥 → 按 V1 或 V2 端点选择对应的--oidc-issuer-url组合启动 oauth2-proxy。两者的关键差异在于V1 使用sts.windows.net发行方并支持--resource资源参数V2 使用login.microsoftonline.com/{tenant}/v2.0发行方、自动追加/.default图 Scope 且忽略--resource。结合 providers/azure.go 的源码实现与 providers/azure_test.go 的测试用例可以对端点选择、租户改写、Scope 追加等内部行为获得确定性的理解从而在排查登录失败、Cookie 过大等问题时有的放矢。【免费下载链接】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），仅供参考
