尧图网站建设 
oauth2-proxy 集成 Azure ADlegacy azure Provider完整指南配置参数、授权端点与迁移到 Microsoft Entra ID【免费下载链接】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 7.14.x 版本中遗留的azureProviderAzure AD Provider为讲解主体覆盖其专属配置参数--azure-tenant、--resource、Azure 门户侧应用注册的完整步骤、V1 与 V2 两类授权端点的命令行配置以及 Cookie 过大、/.default作用域等实战注意事项并结合仓库源码说明其内部实现原理。读完本文你将能独立完成 oauth2-proxy 对接 Azure AD 的部署并理解为何官方推荐逐步迁移到更完善的 Microsoft Entra IDentra-idProvider。一、Provider 定位遗留实现官方标记为 Deprecated在 oauth2-proxy 7.14.x 版本中azure是一个遗留legacy且已标记弃用deprecated的 Provider。官方文档在页面开头便给出明确提示This is the legacy and deprecated provider for Azure, use Microsoft Entra ID if possible.也就是说新部署应优先选用entra-idProvider完全符合 OIDC 规范支持 group overage 与多租户应用但大量存量环境仍在使用azureProvider本文即为这些场景提供完整配置参考并顺带说明两者的差异与迁移方向。从源码上看azureProvider 由providers/azure.go中的NewAzureProvider工厂函数创建其 Provider 显示名为Azure默认 Scope 为openid而entra-id由 providers/ms_entra_id.go 中的NewMicrosoftEntraIDProvider创建内部直接复用 OIDC Provider 的完整实现。两者在 providers/providers.go 中按provider配置值分发azure与entra-id两个分支。二、专属配置参数azureProvider 在通用配置之外仅有两个专属参数不区分命令行形式与配置文件形式均以--前缀的 flag 与 TOML/YAML 字段两种方式暴露FlagToml FieldTypeDescriptionDefault--azure-tenantazure_tenantstringgo to a tenant-specific or common (tenant-independent) endpoint.common--resourceresourcestringThe resource that is protected (Azure AD only)空--azure-tenant控制认证请求指向“租户专属”还是“公共租户无关”端点默认值为common。该参数对应 pkg/apis/options/legacy_options.go 中的AzureTenant字段flag 定义为azure-tenant默认common。在NewAzureProvider中若未指定 tenant则使用common并保持默认登录/兑换 URL一旦指定了 tenant源码会调用overrideTenantURL将登录与兑换端点中的common替换为具体租户。--resource要保护的资源标识仅 Azure AD 生效对应pkg/apis/options/providers.go中的ProtectedResource字段。关键限制源码中明确resource 参数仅在V1 端点下会作为resource表单字段附加到登录请求与令牌兑换请求中使用 V2 端点时该参数不生效NewAzureProvider甚至会在检测到 V2 端点且设置了--resource时打印WARNING: --resource option has no effect when using the Azure OAuth V2 endpoint.的警告日志。三、Azure 门户侧配置步骤App Registration在配置 oauth2-proxy 之前需要先在 Azure 门户完成应用注册。完整步骤如下添加应用访问 https://portal.azure.com选择Azure Active Directory进入App registrations应用注册点击New registration新注册。填写基本信息为应用起一个名称选择受支持的账户类型single-tenant 单租户、multi-tenant 多租户等。在Redirect URI重定向 URI部分为每一个需要被 oauth2-proxy 保护的应用创建一个Web平台条目例如https://internal.yourcompanycom/oauth2/callback然后点击Register注册。添加组读取权限在应用的API PermissionsAPI 权限页面点击Add a permission添加权限选择Microsoft Graph再选择Application permissions应用程序权限点击Group并选择Group.Read.All。点击Add permissions添加权限然后点击Grant admin consent授予管理员同意此操作可能需要管理员账号。IMPORTANT重要即使该权限在门户中显示为Admin consent requiredNo无需管理员同意由于某些你无法看到的 AAD 策略同意操作实际上仍可能是必需的。如果在登录过程中遇到Need admin approval需要管理员批准错误多半就是缺少这一步的权限/同意可选V2 端点必需启用 v2.0 令牌版本如果计划使用 v2.0 Azure Auth 端点请进入应用注册的Manifest清单页面将accessTokenAcceptedVersion: 2写入应用注册清单文件中。生成客户端密钥在应用的Certificates secrets证书和机密页面添加一个新的 client secret客户端机密点击Add后立即记下该值此后将无法再次查看。配置代理按下一节的两种端点形式配置 oauth2-proxy。上述步骤中第 3 步的Group.Read.All权限正是 oauth2-proxy 在 V2 端点下通过 Microsoft Graph 拉取用户组成员列表/v1.0/me/transitiveMemberOf所需的调用权限源码在providers/azure.go的getGroupsFromProfileAPI中携带ConsistencyLevel: eventual请求头分页拉取并用GraphGroupField默认id决定从响应中取id还是displayName作为组标识。四、两种授权端点的代理配置azureProvider 支持两类微软认证端点二者在命令行参数上仅有--oidc-issuer-url不同1. 使用 V1 Azure Auth 端点Azure Active Directory Endpoints ——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}/2. 使用 V2 Azure Auth 端点Microsoft Identity Platform Endpoints ——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.0源码层面的差异NewAzureProvider在检测到登录 URL 中包含v2.0时会判定为 V2 端点isV2Endpoint true并自动在 Scope 末尾追加https://graph.microsoft.com/.default用于保证能正常调用 Microsoft Graph 查询组信息同时会剔除不适用于 V2 的groupsscope打印 WARNING 日志。此外V1 与 V2 在请求参数上的核心区别是resource参数只在 V1 下随登录与兑换请求发送参见GetLoginURL与prepareRedeem中的分支逻辑。五、注意事项与常见坑V2 端点下使用--resource必须追加/.default当以https://login.microsoftonline.com/{tenant-id}/v2.0作为--oidc_issuer_url并配合--resource使用时务必在资源名末尾追加/.default详见微软官方 v2 权限与同意文档中关于默认作用域的说明。不过需要再次强调即使这样做--resource在 V2 端点下实际不生效因此更稳妥的做法是仅依赖openid与自动追加的 Graph.defaultscope。nginx 反向代理下 Cookie 过大问题当azureProvider 与 nginx 及 cookie 会话存储cookie session store配合使用时认证后的 Cookie 可能过大而无法正确传递典型的upstream sent too big header类问题。官方建议两种解决办法增大 nginx 的proxy_buffer_size改用 Redis 会话存储仓库中对应实现位于 pkg/sessions/redis。令牌验证兜底逻辑azureProvider 的verifySessionToken与extractClaimsIntoSession实现了多层兜底——优先校验 ID Token失败则回退到 Access Token从 claims 构建会话时若 ID Token 中取不到邮箱也会回退使用 Access Token 的 claims。这意味着即便个别场景下 ID Token 未由 AAD 正常签名历史上曾有相关 issue登录流程仍能继续但这也要求配置正确的--oidc-issuer-url以确保验证器可用。邮箱兜底查询当从令牌中无法解析出邮箱时Provider 会调用getEmailFromProfileAPI依次尝试 Microsoft Graph/v1.0/me响应中的mail、otherMails[0]、userPrincipalName三个字段作为会话邮箱见getEmailFromJSON。六、会话刷新与会话校验源码级行为刷新令牌RefreshSession会使用存储的 Refresh Token 向兑换端点发起grant_typerefresh_token请求换取新的 Access Token / ID Token / Refresh Token并重新解析 claims 更新会话中的邮箱与组信息redeemRefreshToken。会话校验ValidateSession通过validateToken使用 Access Token 调用 Profile URL默认https://graph.microsoft.com/v1.0/me验证会话是否仍然有效请求头为Authorization: Bearer access_token。这些行为都由 providers/azure.go 中的AzureProvider结构体统一实现相关单元测试位于 providers/azure_test.go。七、迁移到 Microsoft Entra IDentra-id由于azureProvider 已弃用官方强烈建议新项目直接使用entra-idProvider其专属配置项在 pkg/apis/options/providers.go 的MicrosoftEntraIDOptions中定义FlagToml FieldTypeDefault说明--entra-id-allowed-tenantentra_id_allowed_tenantsstring | list空允许所有租户多租户应用下允许的租户白名单需配合关闭 OIDC issuer 校验--entra-id-federated-token-authentra_id_federated_token_authbooleanfalse使用 Azure Workload Identity 投射的联合令牌代替 client secret 做客户端认证一个典型的多租户entra-id配置示例完整配置与 Terraform 示例见 ms_entra_id.mdproviderentra-id oidc_issuer_urlhttps://login.microsoftonline.com/common/v2.0 client_idclient-id client_secretclient-secret insecure_oidc_skip_issuer_verificationtrue scopeopenid profile email User.Read entra_id_allowed_tenants[9188040d-6c67-4c5b-b112-36a304b66dad,my-tenant-id] email_domains*相比azureentra-id在源码层面providers/ms_entra_id.go增加了三项关键能力多租户场景下按 ID Token 的issclaim 校验租户白名单ValidateSession→checkTenantMatchesTenantList组超限group overage超过 200 个组时通过 Microsoft Graph 的transitiveMemberOf分页补齐完整组列表EnrichSession→addGraphGroupsToSession以及使用 Workload Identity 联合凭证完成客户端认证Redeem→redeemWithFederatedToken从而省去 client secret 的托管成本。八、总结若你是存量系统且暂不方便改造可按本文第三、四节的步骤完成azureProvider 的接入记住--azure-tenant默认common、--resource仅 V1 端点生效、V2 端点需在清单中启用accessTokenAcceptedVersion: 2、遇Need admin approval检查Group.Read.All的管理员同意、nginx 下 Cookie 过大时增大proxy_buffer_size或改用 Redis 会话存储。若你是新部署请直接使用entra-idProvider参考 ms_entra_id.md以获得完整的 OIDC 兼容性、组超限处理与 Workload Identity 支持。【免费下载链接】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（legacy azure Provider）完整指南：配置参数、授权端点与迁移到 Microsoft Entra ID
oauth2-proxy 集成 Azure ADlegacy azure Provider完整指南配置参数、授权端点与迁移到 Microsoft Entra ID【免费下载链接】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 7.14.x 版本中遗留的azureProviderAzure AD Provider为讲解主体覆盖其专属配置参数--azure-tenant、--resource、Azure 门户侧应用注册的完整步骤、V1 与 V2 两类授权端点的命令行配置以及 Cookie 过大、/.default作用域等实战注意事项并结合仓库源码说明其内部实现原理。读完本文你将能独立完成 oauth2-proxy 对接 Azure AD 的部署并理解为何官方推荐逐步迁移到更完善的 Microsoft Entra IDentra-idProvider。一、Provider 定位遗留实现官方标记为 Deprecated在 oauth2-proxy 7.14.x 版本中azure是一个遗留legacy且已标记弃用deprecated的 Provider。官方文档在页面开头便给出明确提示This is the legacy and deprecated provider for Azure, use Microsoft Entra ID if possible.也就是说新部署应优先选用entra-idProvider完全符合 OIDC 规范支持 group overage 与多租户应用但大量存量环境仍在使用azureProvider本文即为这些场景提供完整配置参考并顺带说明两者的差异与迁移方向。从源码上看azureProvider 由providers/azure.go中的NewAzureProvider工厂函数创建其 Provider 显示名为Azure默认 Scope 为openid而entra-id由 providers/ms_entra_id.go 中的NewMicrosoftEntraIDProvider创建内部直接复用 OIDC Provider 的完整实现。两者在 providers/providers.go 中按provider配置值分发azure与entra-id两个分支。二、专属配置参数azureProvider 在通用配置之外仅有两个专属参数不区分命令行形式与配置文件形式均以--前缀的 flag 与 TOML/YAML 字段两种方式暴露FlagToml FieldTypeDescriptionDefault--azure-tenantazure_tenantstringgo to a tenant-specific or common (tenant-independent) endpoint.common--resourceresourcestringThe resource that is protected (Azure AD only)空--azure-tenant控制认证请求指向“租户专属”还是“公共租户无关”端点默认值为common。该参数对应 pkg/apis/options/legacy_options.go 中的AzureTenant字段flag 定义为azure-tenant默认common。在NewAzureProvider中若未指定 tenant则使用common并保持默认登录/兑换 URL一旦指定了 tenant源码会调用overrideTenantURL将登录与兑换端点中的common替换为具体租户。--resource要保护的资源标识仅 Azure AD 生效对应pkg/apis/options/providers.go中的ProtectedResource字段。关键限制源码中明确resource 参数仅在V1 端点下会作为resource表单字段附加到登录请求与令牌兑换请求中使用 V2 端点时该参数不生效NewAzureProvider甚至会在检测到 V2 端点且设置了--resource时打印WARNING: --resource option has no effect when using the Azure OAuth V2 endpoint.的警告日志。三、Azure 门户侧配置步骤App Registration在配置 oauth2-proxy 之前需要先在 Azure 门户完成应用注册。完整步骤如下添加应用访问 https://portal.azure.com选择Azure Active Directory进入App registrations应用注册点击New registration新注册。填写基本信息为应用起一个名称选择受支持的账户类型single-tenant 单租户、multi-tenant 多租户等。在Redirect URI重定向 URI部分为每一个需要被 oauth2-proxy 保护的应用创建一个Web平台条目例如https://internal.yourcompanycom/oauth2/callback然后点击Register注册。添加组读取权限在应用的API PermissionsAPI 权限页面点击Add a permission添加权限选择Microsoft Graph再选择Application permissions应用程序权限点击Group并选择Group.Read.All。点击Add permissions添加权限然后点击Grant admin consent授予管理员同意此操作可能需要管理员账号。IMPORTANT重要即使该权限在门户中显示为Admin consent requiredNo无需管理员同意由于某些你无法看到的 AAD 策略同意操作实际上仍可能是必需的。如果在登录过程中遇到Need admin approval需要管理员批准错误多半就是缺少这一步的权限/同意可选V2 端点必需启用 v2.0 令牌版本如果计划使用 v2.0 Azure Auth 端点请进入应用注册的Manifest清单页面将accessTokenAcceptedVersion: 2写入应用注册清单文件中。生成客户端密钥在应用的Certificates secrets证书和机密页面添加一个新的 client secret客户端机密点击Add后立即记下该值此后将无法再次查看。配置代理按下一节的两种端点形式配置 oauth2-proxy。上述步骤中第 3 步的Group.Read.All权限正是 oauth2-proxy 在 V2 端点下通过 Microsoft Graph 拉取用户组成员列表/v1.0/me/transitiveMemberOf所需的调用权限源码在providers/azure.go的getGroupsFromProfileAPI中携带ConsistencyLevel: eventual请求头分页拉取并用GraphGroupField默认id决定从响应中取id还是displayName作为组标识。四、两种授权端点的代理配置azureProvider 支持两类微软认证端点二者在命令行参数上仅有--oidc-issuer-url不同1. 使用 V1 Azure Auth 端点Azure Active Directory Endpoints ——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}/2. 使用 V2 Azure Auth 端点Microsoft Identity Platform Endpoints ——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.0源码层面的差异NewAzureProvider在检测到登录 URL 中包含v2.0时会判定为 V2 端点isV2Endpoint true并自动在 Scope 末尾追加https://graph.microsoft.com/.default用于保证能正常调用 Microsoft Graph 查询组信息同时会剔除不适用于 V2 的groupsscope打印 WARNING 日志。此外V1 与 V2 在请求参数上的核心区别是resource参数只在 V1 下随登录与兑换请求发送参见GetLoginURL与prepareRedeem中的分支逻辑。五、注意事项与常见坑V2 端点下使用--resource必须追加/.default当以https://login.microsoftonline.com/{tenant-id}/v2.0作为--oidc_issuer_url并配合--resource使用时务必在资源名末尾追加/.default详见微软官方 v2 权限与同意文档中关于默认作用域的说明。不过需要再次强调即使这样做--resource在 V2 端点下实际不生效因此更稳妥的做法是仅依赖openid与自动追加的 Graph.defaultscope。nginx 反向代理下 Cookie 过大问题当azureProvider 与 nginx 及 cookie 会话存储cookie session store配合使用时认证后的 Cookie 可能过大而无法正确传递典型的upstream sent too big header类问题。官方建议两种解决办法增大 nginx 的proxy_buffer_size改用 Redis 会话存储仓库中对应实现位于 pkg/sessions/redis。令牌验证兜底逻辑azureProvider 的verifySessionToken与extractClaimsIntoSession实现了多层兜底——优先校验 ID Token失败则回退到 Access Token从 claims 构建会话时若 ID Token 中取不到邮箱也会回退使用 Access Token 的 claims。这意味着即便个别场景下 ID Token 未由 AAD 正常签名历史上曾有相关 issue登录流程仍能继续但这也要求配置正确的--oidc-issuer-url以确保验证器可用。邮箱兜底查询当从令牌中无法解析出邮箱时Provider 会调用getEmailFromProfileAPI依次尝试 Microsoft Graph/v1.0/me响应中的mail、otherMails[0]、userPrincipalName三个字段作为会话邮箱见getEmailFromJSON。六、会话刷新与会话校验源码级行为刷新令牌RefreshSession会使用存储的 Refresh Token 向兑换端点发起grant_typerefresh_token请求换取新的 Access Token / ID Token / Refresh Token并重新解析 claims 更新会话中的邮箱与组信息redeemRefreshToken。会话校验ValidateSession通过validateToken使用 Access Token 调用 Profile URL默认https://graph.microsoft.com/v1.0/me验证会话是否仍然有效请求头为Authorization: Bearer access_token。这些行为都由 providers/azure.go 中的AzureProvider结构体统一实现相关单元测试位于 providers/azure_test.go。七、迁移到 Microsoft Entra IDentra-id由于azureProvider 已弃用官方强烈建议新项目直接使用entra-idProvider其专属配置项在 pkg/apis/options/providers.go 的MicrosoftEntraIDOptions中定义FlagToml FieldTypeDefault说明--entra-id-allowed-tenantentra_id_allowed_tenantsstring | list空允许所有租户多租户应用下允许的租户白名单需配合关闭 OIDC issuer 校验--entra-id-federated-token-authentra_id_federated_token_authbooleanfalse使用 Azure Workload Identity 投射的联合令牌代替 client secret 做客户端认证一个典型的多租户entra-id配置示例完整配置与 Terraform 示例见 ms_entra_id.mdproviderentra-id oidc_issuer_urlhttps://login.microsoftonline.com/common/v2.0 client_idclient-id client_secretclient-secret insecure_oidc_skip_issuer_verificationtrue scopeopenid profile email User.Read entra_id_allowed_tenants[9188040d-6c67-4c5b-b112-36a304b66dad,my-tenant-id] email_domains*相比azureentra-id在源码层面providers/ms_entra_id.go增加了三项关键能力多租户场景下按 ID Token 的issclaim 校验租户白名单ValidateSession→checkTenantMatchesTenantList组超限group overage超过 200 个组时通过 Microsoft Graph 的transitiveMemberOf分页补齐完整组列表EnrichSession→addGraphGroupsToSession以及使用 Workload Identity 联合凭证完成客户端认证Redeem→redeemWithFederatedToken从而省去 client secret 的托管成本。八、总结若你是存量系统且暂不方便改造可按本文第三、四节的步骤完成azureProvider 的接入记住--azure-tenant默认common、--resource仅 V1 端点生效、V2 端点需在清单中启用accessTokenAcceptedVersion: 2、遇Need admin approval检查Group.Read.All的管理员同意、nginx 下 Cookie 过大时增大proxy_buffer_size或改用 Redis 会话存储。若你是新部署请直接使用entra-idProvider参考 ms_entra_id.md以获得完整的 OIDC 兼容性、组超限处理与 Workload Identity 支持。【免费下载链接】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），仅供参考