oauth2-proxy 接入 Google 身份认证全指南OAuth 客户端注册、Workspace 组授权与 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导读本文围绕 oauth2-proxy 的 Google Provider默认身份提供商展开系统讲解从 Google Cloud Console 创建 OAuth 客户端、配置回调地址到基于 Google Workspace 域内邮件组做精细化授权再到以 Application Default CredentialsADC/ Workload Identity 免密钥部署的完整链路。读完本文你将掌握--google-*系列全部配置项的真实含义与组合方式理解 oauth2-proxy 在认证Redeem、组校验Group Validation、令牌刷新Refresh三个阶段分别做了什么并能在 GCP 内外部环境完成可落地的生产配置。本文以 v7.9.x 版 Google Provider 文档 为骨架结合当前仓库 providers/google.go 源码与 pkg/apis/options/providers.go 配置定义做源码级印证。一、Google Provider 配置项总览在 oauth2-proxy 中启用 Google Provider只需将provider设置为google。下表完整列出 v7.9.x 文档中与 Google 相关的全部配置项并标注了对应的命令行 Flag 与 TOML 字段名可在 pkg/apis/options/legacy_options.go 中核对字段定义FlagToml FieldTypeDescriptionDefault--google-admin-emailgoogle_admin_emailstring用于模拟调用 API 的 Google 管理员邮箱--google-groupgoogle_groupsstring仅允许属于该 Google 组的用户登录可多次指定--google-service-account-jsongoogle_service_account_jsonstring服务账号 JSON 凭据文件的路径--google-use-application-default-credentialsgoogle_use_application_default_credentialsbool使用应用默认凭据ADC而非服务账号 JSON例如 GKE Workload Identity--google-target-principalgoogle_target_principalbool使用 ADC 时模拟的目标 principal默认为 ADC 所配置的服务账号说明几点细节--google-group是字符串切片StringSlice类型可以重复传入多个组用户只要属于任意一个被配置的组即可通过授权从源码看该选项同时映射了google_group旧与google_groups新两个 cfg 键以保持向后兼容见 legacy_options.go。在较新的仓库版本对应 alpha_config.md 中GoogleOptions的结构定义与 providers.go中还新增了两个与组织 ID 相关的选项--google-use-organization-idgoogle_use_organization_idbool将组织 ID 用作 preferred username默认false见 pkg/apis/options/providers.go 中DefaultGoogleUseOrganizationID false--google-admin-api-user-scopegoogle_admin_api_user_scopestring查询 Admin SDK 获取组织 ID 时使用的 OAuth scope可为readonly、user或cloud默认readonly。这两个选项在 v7.9.x 文档中尚未收录若你使用的版本较新可按需启用。二、在 Google Cloud Console 注册 OAuth 客户端使用 Google 作为身份提供商第一步是在 Google Cloud Console 中创建 OAuth 客户端。完整注册步骤如下对应原文档 Usage 部分创建新项目进入 Google Cloud Consoleconsole.developers.google.com/project创建项目。如果当前选中了其他项目请从右上角项目下拉框切换到你刚创建的新项目。在项目 Dashboard 中心面板选择APIs ServicesAPI 与服务。在左侧导航面板选择Credentials凭据。在中心面板选择OAuth consent screenOAuth 同意屏幕标签页填写Product name shown to users向用户显示的产品名称并保存。在中心面板选择Credentials标签页展开New credentials新建凭据下拉框选择OAuth client IDOAuth 客户端 ID选择Web applicationWeb 应用类型应用名称可自由填写取一个合适的名称即可Authorized JavaScript origins已获授权的 JavaScript 来源填写你的域名例如https://internal.yourcompany.comAuthorized redirect URIs已获授权的重定向 URI填写 oauth2-proxy 回调地址例如https://internal.yourcompany.com/oauth2/callback点击Create创建。记下生成的Client ID与Client Secret稍后填入 oauth2-proxy 的client-id/client-secret对应配置文件中的client_id/client_secret参见 contrib/oauth2-proxy.cfg.example。关于回调地址的说明回调路径/oauth2/callback是 oauth2-proxy 的固定 OAuth 回调端点可在仓库文档 features/endpoints.md 中确认该地址必须与 Google 控制台中登记的 Authorized redirect URIs 完全一致包括协议、域名、端口否则授权流程会在回调阶段被 Google 拒绝。若配置了redirect_url则以此为准否则默认使用https:// 请求 Host /oauth2/callback。三、推荐配合 cookie-refresh 缩短会话刷新周期原文档特别建议使用短刷新间隔1 小时的cookie-refresh设置来刷新会话从而周期性地校验用户账号仍处于授权状态。原理上cookie-refresh会在会话建立超过指定时长后在后续请求中触发对 OAuth 令牌的重新校验refresh。对于启用了组限制的部署这意味着用户即使初始认证通过若之后被移出 Google 组最迟在下一次刷新时约每小时就会被拒绝访问。配置示例oauth2-proxy \ --providergoogle \ --client-id123456.apps.googleusercontent.com \ --client-secretYOUR_CLIENT_SECRET \ --email-domainyourcompany.com \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secret0123456789abcdef0123456789abcdef \ --cookie-refresh1h对应 TOML 配置文件写法为cookie_refresh 1h见 contrib/oauth2-proxy.cfg.example。从源码层面看会话刷新会调用GoogleProvider.RefreshSessionproviders/google.go该函数在用 refresh_token 换取新令牌后会再次执行 groupValidator 校验若用户已不在配置的组内刷新会被拒绝并返回错误这正是刷新校验账号仍被授权的落地实现。四、可选将登录限制到指定 Google Workspace 域内组如果你希望只允许 Google Workspace 域内特定邮件组的成员访问需要按以下步骤完成服务账号配置与 API 授权。这套流程依赖 Google Admin SDK 目录 API 来查询组成员关系。4.1 完整配置步骤创建服务账号并配置其使用 Application Default Credentials / Workload Identity / Workload Identity Federation推荐见下文第六节或者直接下载其 JSON 凭据文件。记下该服务账号的 Client ID后续步骤会用到。在 APIs Auth 下选择 APIs。找到Admin SDK并点击 Enable API启用 API。按照 Google 官方为服务账号设置域范围委派domain-wide delegation的步骤将第 2 步记下的 Client ID 授权以下 OAuth scopehttps://www.googleapis.com/auth/admin.directory.group.readonly https://www.googleapis.com/auth/admin.directory.user.readonly说明v7.9.x 文档要求上述两个 scope在新版本文档中组查询 scope 调整为https://www.googleapis.com/auth/admin.directory.group.member.readonly。从当前仓库源码 providers/google.go 的possibleScopesList看oauth2-proxy 实际会依次尝试admin.directory.group.member.readonly、admin.directory.group.readonly、admin.directory.group.member、admin.directory.group四组 scope只要其中一组能取到令牌即成功因此请至少为服务账号授予列表中的某一个组目录 scope。按照 Google Workspace 管理控制台文档support.google.com/a/answer/60757的说明启用 Admin API 访问权限。在 Gmail 域中选择一个现有的管理邮箱或新建一个将其分配给google-admin-email--google-admin-email标志。该邮箱将被 oauth2-proxy 模拟impersonate用于发起 Admin SDK 调用。域范围委派要求服务账号以某个管理员的身份代为操作这就是需要配置管理员邮箱的原因。创建一个现有的邮件组或选择一个已有组将该组邮箱设置为google-group--google-group标志的值。可以重复传入该标志配置多个组用户会被依次检查是否属于其中任一组成员。仅当使用 JSON 凭据文件即第 1 步选择下载 JSON 时收紧第 1 步下载的 JSON 文件权限确保只有 oauth2-proxy 进程能读取该文件并将文件路径设置到google-service-account-json--google-service-account-json标志。重启 oauth2-proxy 使配置生效。4.2 组校验的行为与注意点校验时机用户会在初始认证时以及每次令牌刷新时大约每小时一次被检查是否仍属于配置的组成员列表。这一点既写在了文档中也体现在源码中RefreshSession在换取新令牌后会再次调用p.groupValidator(s)若校验失败则拒绝刷新providers/google.go。实现方式组校验通过 Admin Directory API 的Members.HasMember接口逐个组检查用户是否属于该组支持嵌套子组的成员判定。源码 providers/google.go 中对两类异常做了处理当组不存在HTTP 404时记录错误并返回 false当HasMember返回 400典型场景是成员邮箱与组不在同一域如memberotherdomain.com在groupmydomain.com中时会退化为直接查询该组的成员对象且仅当成员状态为ACTIVE时才判定属于该组。仅使用 JSON 时必须同时保证 JSON 文件权限收敛步骤 9避免其他进程可读导致凭据泄露。未配置组时若配置了服务账号或默认凭据但未指定--google-group较新版本的 oauth2-proxy 会调用populateAllGroupsproviders/google.go在会话中填充用户的全部组信息而不再限制访问即便拉取组列表失败也会放行访问。若未配置任何凭据则组校验直接放行默认的 groupValidator 恒返回 true见 providers/google.go。五、推荐使用 ADC / Workload Identity / Workload Identity Federation原文档将 Application Default CredentialsADC作为推荐的凭据方式应用默认凭据ADCoauth2-proxy 可以自动利用 Google 应用默认凭据体系。当部署在 GCP 内部时它能够自动使用绑定到资源上的服务账号无需在部署环境中存放任何密钥文件。GKE Workload Identity当部署在 GKEGoogle Kubernetes Engine中时可通过 Workload Identity 特性利用 ADC。按 Google 官方 Workload Identity 配置指南在 GKE 上完成绑定后Pod 内的 oauth2-proxy 无需再挂载服务账号 JSON仅需开启--google-use-application-default-credentials即可。GKE 之外 / 混合云当部署在 GCP 之外时可以考虑使用 Workload Identity FederationWIF通过外部身份池将本地环境的身份映射为 Google 服务账号从而同样免去密钥文件。启用方式oauth2-proxy \ --providergoogle \ --client-id123456.apps.googleusercontent.com \ --client-secretYOUR_CLIENT_SECRET \ --email-domainyourcompany.com \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secret0123456789abcdef0123456789abcdef \ --google-admin-emailadminyourcompany.com \ --google-groupengineeringyourcompany.com \ --google-use-application-default-credentialstrue源码层面providers/google.go启用 ADC 时oauth2-proxy 通过impersonate.CredentialsTokenSource构造令牌源其中Subject即--google-admin-email指定的管理员TargetPrincipal优先取--google-target-principal未显式设置时则会尝试从 ADC 凭据 JSON 中的client_email自动推断若运行在 GCE 实例上还会通过元数据服务metadata server获取providers/google.go。两种凭据方式的互斥与校验校验逻辑 明确了以下几点规则配置前值得留意如果既未配置google-admin-email也未配置google-service-account-json/google-use-application-default-credentials则跳过校验即纯 OAuth 登录、不做组限制时这些选项均可省略。只要配置了任一凭据就必须提供google-admin-email否则报错missing setting: google-admin-email。未开启 ADC 时必须提供google-service-account-json且该文件必须真实存在否则分别报missing setting: google-service-account-json or google-use-application-default-credentials或Google credentials file not found: path。google-service-account-json与google-use-application-default-credentials不能同时启用否则报invalid setting: cant use both ...。六、源码视角GoogleProvider 的认证与授权流程结合 providers/google.go 可以把 Google Provider 的完整工作链路拆解为三个阶段便于排查问题时对号入座。6.1 默认端点与 ScopeNewGoogleProviderproviders/google.go会为 Google Provider 设置一组默认端点与默认 scope用途默认值登录端点 LoginURLhttps://accounts.google.com/o/oauth2/auth?access_typeoffline携带access_typeoffline以获取 refresh token令牌兑换端点 RedeemURLhttps://www.googleapis.com/oauth2/v3/token令牌校验端点 ValidateURLhttps://www.googleapis.com/oauth2/v1/tokeninfo默认 Scopeprofile email这意味着即便你不显式配置login-url/redeem-url/validate-urloauth2-proxy 也会自动使用上述 Google 官方端点完成标准 OAuth2 流程。6.2 认证兑换阶段Redeem当用户通过 Google 授权页回调后Redeemproviders/google.go用授权码code向令牌端点换取令牌响应中包含access_token、refresh_token、expires_in与id_token。随后claimsFromIDTokenproviders/google.go对id_token的第二段JWT Payload做 base64url 解码提取sub作为会话 User、email、email_verified三个声明——其中邮箱缺失或未被验证时兑换会直接失败。最终写入会话的字段包括 AccessToken、IDToken、RefreshToken、Email 与 User。6.3 组校验与用户名增强EnrichSessionEnrichSessionproviders/google.go在认证后执行两件事调用groupValidator填充会话的Groups字段。若配置了--google-group则通过setGroupRestriction逐组调用Members.HasMember把用户实际所属的组写入session.Groups返回是否存在至少一个匹配组providers/google.go未配置组且启用了凭据时则通过getUserGroups分页拉取用户全部组每页最多 200 个自动翻页见 providers/google.go。若启用了google-use-organization-id则通过getUserInfo调用 Admin Directory 的Users.Get接口从用户的ExternalIds中提取类型为organization的 ID 作为PreferredUsernameproviders/google.go。6.4 会话刷新阶段RefreshSessionRefreshSessionproviders/google.go首先通过 refresh_token 向令牌端点发起grant_typerefresh_token请求换取新的 access_token 与 id_tokenredeemRefreshToken随后再次执行组校验。也就是说组授权状态不是一次性快照而是随刷新持续收敛的——这正是前文建议cookie-refresh1h的源码依据。七、配置示例汇总7.1 纯 OAuth 登录不做组限制最简配置只需--providergoogle 客户端凭据 允许的邮箱域oauth2-proxy \ --providergoogle \ --client-id123456.apps.googleusercontent.com \ --client-secretYOUR_CLIENT_SECRET \ --email-domainyourcompany.com \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secret0123456789abcdef0123456789abcdef7.2 TOML 配置文件含组限制JSON 凭据参考 contrib/oauth2-proxy.cfg.example 的字段风格provider google client_id 123456.apps.googleusercontent.com client_secret YOUR_CLIENT_SECRET email_domains [yourcompany.com] upstreams [http://127.0.0.1:8080/] cookie_secret 0123456789abcdef0123456789abcdef cookie_refresh 1h google_admin_email adminyourcompany.com google_groups [engineeringyourcompany.com, platformyourcompany.com] google_service_account_json /etc/oauth2-proxy/google-service-account.json7.3 Alpha 配置新版 YAML 配置格式在当前仓库源码中Google 专属配置在 Alpha 配置格式下位于provider.googleConfig结构内字段定义见 pkg/apis/options/providers.go文档化说明见 alpha_config.md 的 GoogleOptions 小节provider: type: google googleConfig: group: - engineeringyourcompany.com adminEmail: adminyourcompany.com serviceAccountJson: /etc/oauth2-proxy/google-service-account.json useApplicationDefaultCredentials: true targetPrincipal: oauth2-proxy-sayour-project.iam.gserviceaccount.com useOrganizationID: false adminAPIUserScope: readonly注意useApplicationDefaultCredentials与serviceAccountJson二选一targetPrincipal仅在开启 ADC 且需要显式指定模拟对象时填写。八、常见问题与排障要点回调 404 / 授权失败先核对 Google 控制台登记的 Authorized redirect URIs 与 oauth2-proxy 实际回调地址默认https://host/oauth2/callback是否完全一致。组限制不生效检查是否同时配置了google-admin-email与服务账号/ADC 凭据确认 Admin SDK API 已启用确认域范围委派中授予了组目录相关 scope见 4.1 节 scope 列表。报错 google credentials do not have enough permissions to access admin API scope说明服务账号对配置的 scope 无权限getAdminService在遍历possibleScopesList后仍无法取得令牌providers/google.go需要回控制台补齐 scope。跨域成员判定为 400非本域成员在HasMember下可能返回 400oauth2-proxy 会自动退化为Members.Get并校验成员状态为ACTIVE才放行providers/google.go。GKE 上不想挂载 JSON启用--google-use-application-default-credentials并配合 Workload Identity 绑定无需任何密钥文件。九、相关资源本文核心依据文档v7.9.x Google Provider 文档Google Provider 实现源码providers/google.go 及测试 providers/google_test.goGoogleOptions 配置结构定义pkg/apis/options/providers.goGoogle 配置校验规则pkg/validation/providers.go命令行 Flag 定义pkg/apis/options/legacy_options.go通用配置文件示例contrib/oauth2-proxy.cfg.example【免费下载链接】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 接入 Google 身份认证全指南：OAuth 客户端注册、Workspace 组授权与 Workload Identity 实战
oauth2-proxy 接入 Google 身份认证全指南OAuth 客户端注册、Workspace 组授权与 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导读本文围绕 oauth2-proxy 的 Google Provider默认身份提供商展开系统讲解从 Google Cloud Console 创建 OAuth 客户端、配置回调地址到基于 Google Workspace 域内邮件组做精细化授权再到以 Application Default CredentialsADC/ Workload Identity 免密钥部署的完整链路。读完本文你将掌握--google-*系列全部配置项的真实含义与组合方式理解 oauth2-proxy 在认证Redeem、组校验Group Validation、令牌刷新Refresh三个阶段分别做了什么并能在 GCP 内外部环境完成可落地的生产配置。本文以 v7.9.x 版 Google Provider 文档 为骨架结合当前仓库 providers/google.go 源码与 pkg/apis/options/providers.go 配置定义做源码级印证。一、Google Provider 配置项总览在 oauth2-proxy 中启用 Google Provider只需将provider设置为google。下表完整列出 v7.9.x 文档中与 Google 相关的全部配置项并标注了对应的命令行 Flag 与 TOML 字段名可在 pkg/apis/options/legacy_options.go 中核对字段定义FlagToml FieldTypeDescriptionDefault--google-admin-emailgoogle_admin_emailstring用于模拟调用 API 的 Google 管理员邮箱--google-groupgoogle_groupsstring仅允许属于该 Google 组的用户登录可多次指定--google-service-account-jsongoogle_service_account_jsonstring服务账号 JSON 凭据文件的路径--google-use-application-default-credentialsgoogle_use_application_default_credentialsbool使用应用默认凭据ADC而非服务账号 JSON例如 GKE Workload Identity--google-target-principalgoogle_target_principalbool使用 ADC 时模拟的目标 principal默认为 ADC 所配置的服务账号说明几点细节--google-group是字符串切片StringSlice类型可以重复传入多个组用户只要属于任意一个被配置的组即可通过授权从源码看该选项同时映射了google_group旧与google_groups新两个 cfg 键以保持向后兼容见 legacy_options.go。在较新的仓库版本对应 alpha_config.md 中GoogleOptions的结构定义与 providers.go中还新增了两个与组织 ID 相关的选项--google-use-organization-idgoogle_use_organization_idbool将组织 ID 用作 preferred username默认false见 pkg/apis/options/providers.go 中DefaultGoogleUseOrganizationID false--google-admin-api-user-scopegoogle_admin_api_user_scopestring查询 Admin SDK 获取组织 ID 时使用的 OAuth scope可为readonly、user或cloud默认readonly。这两个选项在 v7.9.x 文档中尚未收录若你使用的版本较新可按需启用。二、在 Google Cloud Console 注册 OAuth 客户端使用 Google 作为身份提供商第一步是在 Google Cloud Console 中创建 OAuth 客户端。完整注册步骤如下对应原文档 Usage 部分创建新项目进入 Google Cloud Consoleconsole.developers.google.com/project创建项目。如果当前选中了其他项目请从右上角项目下拉框切换到你刚创建的新项目。在项目 Dashboard 中心面板选择APIs ServicesAPI 与服务。在左侧导航面板选择Credentials凭据。在中心面板选择OAuth consent screenOAuth 同意屏幕标签页填写Product name shown to users向用户显示的产品名称并保存。在中心面板选择Credentials标签页展开New credentials新建凭据下拉框选择OAuth client IDOAuth 客户端 ID选择Web applicationWeb 应用类型应用名称可自由填写取一个合适的名称即可Authorized JavaScript origins已获授权的 JavaScript 来源填写你的域名例如https://internal.yourcompany.comAuthorized redirect URIs已获授权的重定向 URI填写 oauth2-proxy 回调地址例如https://internal.yourcompany.com/oauth2/callback点击Create创建。记下生成的Client ID与Client Secret稍后填入 oauth2-proxy 的client-id/client-secret对应配置文件中的client_id/client_secret参见 contrib/oauth2-proxy.cfg.example。关于回调地址的说明回调路径/oauth2/callback是 oauth2-proxy 的固定 OAuth 回调端点可在仓库文档 features/endpoints.md 中确认该地址必须与 Google 控制台中登记的 Authorized redirect URIs 完全一致包括协议、域名、端口否则授权流程会在回调阶段被 Google 拒绝。若配置了redirect_url则以此为准否则默认使用https:// 请求 Host /oauth2/callback。三、推荐配合 cookie-refresh 缩短会话刷新周期原文档特别建议使用短刷新间隔1 小时的cookie-refresh设置来刷新会话从而周期性地校验用户账号仍处于授权状态。原理上cookie-refresh会在会话建立超过指定时长后在后续请求中触发对 OAuth 令牌的重新校验refresh。对于启用了组限制的部署这意味着用户即使初始认证通过若之后被移出 Google 组最迟在下一次刷新时约每小时就会被拒绝访问。配置示例oauth2-proxy \ --providergoogle \ --client-id123456.apps.googleusercontent.com \ --client-secretYOUR_CLIENT_SECRET \ --email-domainyourcompany.com \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secret0123456789abcdef0123456789abcdef \ --cookie-refresh1h对应 TOML 配置文件写法为cookie_refresh 1h见 contrib/oauth2-proxy.cfg.example。从源码层面看会话刷新会调用GoogleProvider.RefreshSessionproviders/google.go该函数在用 refresh_token 换取新令牌后会再次执行 groupValidator 校验若用户已不在配置的组内刷新会被拒绝并返回错误这正是刷新校验账号仍被授权的落地实现。四、可选将登录限制到指定 Google Workspace 域内组如果你希望只允许 Google Workspace 域内特定邮件组的成员访问需要按以下步骤完成服务账号配置与 API 授权。这套流程依赖 Google Admin SDK 目录 API 来查询组成员关系。4.1 完整配置步骤创建服务账号并配置其使用 Application Default Credentials / Workload Identity / Workload Identity Federation推荐见下文第六节或者直接下载其 JSON 凭据文件。记下该服务账号的 Client ID后续步骤会用到。在 APIs Auth 下选择 APIs。找到Admin SDK并点击 Enable API启用 API。按照 Google 官方为服务账号设置域范围委派domain-wide delegation的步骤将第 2 步记下的 Client ID 授权以下 OAuth scopehttps://www.googleapis.com/auth/admin.directory.group.readonly https://www.googleapis.com/auth/admin.directory.user.readonly说明v7.9.x 文档要求上述两个 scope在新版本文档中组查询 scope 调整为https://www.googleapis.com/auth/admin.directory.group.member.readonly。从当前仓库源码 providers/google.go 的possibleScopesList看oauth2-proxy 实际会依次尝试admin.directory.group.member.readonly、admin.directory.group.readonly、admin.directory.group.member、admin.directory.group四组 scope只要其中一组能取到令牌即成功因此请至少为服务账号授予列表中的某一个组目录 scope。按照 Google Workspace 管理控制台文档support.google.com/a/answer/60757的说明启用 Admin API 访问权限。在 Gmail 域中选择一个现有的管理邮箱或新建一个将其分配给google-admin-email--google-admin-email标志。该邮箱将被 oauth2-proxy 模拟impersonate用于发起 Admin SDK 调用。域范围委派要求服务账号以某个管理员的身份代为操作这就是需要配置管理员邮箱的原因。创建一个现有的邮件组或选择一个已有组将该组邮箱设置为google-group--google-group标志的值。可以重复传入该标志配置多个组用户会被依次检查是否属于其中任一组成员。仅当使用 JSON 凭据文件即第 1 步选择下载 JSON 时收紧第 1 步下载的 JSON 文件权限确保只有 oauth2-proxy 进程能读取该文件并将文件路径设置到google-service-account-json--google-service-account-json标志。重启 oauth2-proxy 使配置生效。4.2 组校验的行为与注意点校验时机用户会在初始认证时以及每次令牌刷新时大约每小时一次被检查是否仍属于配置的组成员列表。这一点既写在了文档中也体现在源码中RefreshSession在换取新令牌后会再次调用p.groupValidator(s)若校验失败则拒绝刷新providers/google.go。实现方式组校验通过 Admin Directory API 的Members.HasMember接口逐个组检查用户是否属于该组支持嵌套子组的成员判定。源码 providers/google.go 中对两类异常做了处理当组不存在HTTP 404时记录错误并返回 false当HasMember返回 400典型场景是成员邮箱与组不在同一域如memberotherdomain.com在groupmydomain.com中时会退化为直接查询该组的成员对象且仅当成员状态为ACTIVE时才判定属于该组。仅使用 JSON 时必须同时保证 JSON 文件权限收敛步骤 9避免其他进程可读导致凭据泄露。未配置组时若配置了服务账号或默认凭据但未指定--google-group较新版本的 oauth2-proxy 会调用populateAllGroupsproviders/google.go在会话中填充用户的全部组信息而不再限制访问即便拉取组列表失败也会放行访问。若未配置任何凭据则组校验直接放行默认的 groupValidator 恒返回 true见 providers/google.go。五、推荐使用 ADC / Workload Identity / Workload Identity Federation原文档将 Application Default CredentialsADC作为推荐的凭据方式应用默认凭据ADCoauth2-proxy 可以自动利用 Google 应用默认凭据体系。当部署在 GCP 内部时它能够自动使用绑定到资源上的服务账号无需在部署环境中存放任何密钥文件。GKE Workload Identity当部署在 GKEGoogle Kubernetes Engine中时可通过 Workload Identity 特性利用 ADC。按 Google 官方 Workload Identity 配置指南在 GKE 上完成绑定后Pod 内的 oauth2-proxy 无需再挂载服务账号 JSON仅需开启--google-use-application-default-credentials即可。GKE 之外 / 混合云当部署在 GCP 之外时可以考虑使用 Workload Identity FederationWIF通过外部身份池将本地环境的身份映射为 Google 服务账号从而同样免去密钥文件。启用方式oauth2-proxy \ --providergoogle \ --client-id123456.apps.googleusercontent.com \ --client-secretYOUR_CLIENT_SECRET \ --email-domainyourcompany.com \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secret0123456789abcdef0123456789abcdef \ --google-admin-emailadminyourcompany.com \ --google-groupengineeringyourcompany.com \ --google-use-application-default-credentialstrue源码层面providers/google.go启用 ADC 时oauth2-proxy 通过impersonate.CredentialsTokenSource构造令牌源其中Subject即--google-admin-email指定的管理员TargetPrincipal优先取--google-target-principal未显式设置时则会尝试从 ADC 凭据 JSON 中的client_email自动推断若运行在 GCE 实例上还会通过元数据服务metadata server获取providers/google.go。两种凭据方式的互斥与校验校验逻辑 明确了以下几点规则配置前值得留意如果既未配置google-admin-email也未配置google-service-account-json/google-use-application-default-credentials则跳过校验即纯 OAuth 登录、不做组限制时这些选项均可省略。只要配置了任一凭据就必须提供google-admin-email否则报错missing setting: google-admin-email。未开启 ADC 时必须提供google-service-account-json且该文件必须真实存在否则分别报missing setting: google-service-account-json or google-use-application-default-credentials或Google credentials file not found: path。google-service-account-json与google-use-application-default-credentials不能同时启用否则报invalid setting: cant use both ...。六、源码视角GoogleProvider 的认证与授权流程结合 providers/google.go 可以把 Google Provider 的完整工作链路拆解为三个阶段便于排查问题时对号入座。6.1 默认端点与 ScopeNewGoogleProviderproviders/google.go会为 Google Provider 设置一组默认端点与默认 scope用途默认值登录端点 LoginURLhttps://accounts.google.com/o/oauth2/auth?access_typeoffline携带access_typeoffline以获取 refresh token令牌兑换端点 RedeemURLhttps://www.googleapis.com/oauth2/v3/token令牌校验端点 ValidateURLhttps://www.googleapis.com/oauth2/v1/tokeninfo默认 Scopeprofile email这意味着即便你不显式配置login-url/redeem-url/validate-urloauth2-proxy 也会自动使用上述 Google 官方端点完成标准 OAuth2 流程。6.2 认证兑换阶段Redeem当用户通过 Google 授权页回调后Redeemproviders/google.go用授权码code向令牌端点换取令牌响应中包含access_token、refresh_token、expires_in与id_token。随后claimsFromIDTokenproviders/google.go对id_token的第二段JWT Payload做 base64url 解码提取sub作为会话 User、email、email_verified三个声明——其中邮箱缺失或未被验证时兑换会直接失败。最终写入会话的字段包括 AccessToken、IDToken、RefreshToken、Email 与 User。6.3 组校验与用户名增强EnrichSessionEnrichSessionproviders/google.go在认证后执行两件事调用groupValidator填充会话的Groups字段。若配置了--google-group则通过setGroupRestriction逐组调用Members.HasMember把用户实际所属的组写入session.Groups返回是否存在至少一个匹配组providers/google.go未配置组且启用了凭据时则通过getUserGroups分页拉取用户全部组每页最多 200 个自动翻页见 providers/google.go。若启用了google-use-organization-id则通过getUserInfo调用 Admin Directory 的Users.Get接口从用户的ExternalIds中提取类型为organization的 ID 作为PreferredUsernameproviders/google.go。6.4 会话刷新阶段RefreshSessionRefreshSessionproviders/google.go首先通过 refresh_token 向令牌端点发起grant_typerefresh_token请求换取新的 access_token 与 id_tokenredeemRefreshToken随后再次执行组校验。也就是说组授权状态不是一次性快照而是随刷新持续收敛的——这正是前文建议cookie-refresh1h的源码依据。七、配置示例汇总7.1 纯 OAuth 登录不做组限制最简配置只需--providergoogle 客户端凭据 允许的邮箱域oauth2-proxy \ --providergoogle \ --client-id123456.apps.googleusercontent.com \ --client-secretYOUR_CLIENT_SECRET \ --email-domainyourcompany.com \ --upstreamhttp://127.0.0.1:8080 \ --cookie-secret0123456789abcdef0123456789abcdef7.2 TOML 配置文件含组限制JSON 凭据参考 contrib/oauth2-proxy.cfg.example 的字段风格provider google client_id 123456.apps.googleusercontent.com client_secret YOUR_CLIENT_SECRET email_domains [yourcompany.com] upstreams [http://127.0.0.1:8080/] cookie_secret 0123456789abcdef0123456789abcdef cookie_refresh 1h google_admin_email adminyourcompany.com google_groups [engineeringyourcompany.com, platformyourcompany.com] google_service_account_json /etc/oauth2-proxy/google-service-account.json7.3 Alpha 配置新版 YAML 配置格式在当前仓库源码中Google 专属配置在 Alpha 配置格式下位于provider.googleConfig结构内字段定义见 pkg/apis/options/providers.go文档化说明见 alpha_config.md 的 GoogleOptions 小节provider: type: google googleConfig: group: - engineeringyourcompany.com adminEmail: adminyourcompany.com serviceAccountJson: /etc/oauth2-proxy/google-service-account.json useApplicationDefaultCredentials: true targetPrincipal: oauth2-proxy-sayour-project.iam.gserviceaccount.com useOrganizationID: false adminAPIUserScope: readonly注意useApplicationDefaultCredentials与serviceAccountJson二选一targetPrincipal仅在开启 ADC 且需要显式指定模拟对象时填写。八、常见问题与排障要点回调 404 / 授权失败先核对 Google 控制台登记的 Authorized redirect URIs 与 oauth2-proxy 实际回调地址默认https://host/oauth2/callback是否完全一致。组限制不生效检查是否同时配置了google-admin-email与服务账号/ADC 凭据确认 Admin SDK API 已启用确认域范围委派中授予了组目录相关 scope见 4.1 节 scope 列表。报错 google credentials do not have enough permissions to access admin API scope说明服务账号对配置的 scope 无权限getAdminService在遍历possibleScopesList后仍无法取得令牌providers/google.go需要回控制台补齐 scope。跨域成员判定为 400非本域成员在HasMember下可能返回 400oauth2-proxy 会自动退化为Members.Get并校验成员状态为ACTIVE才放行providers/google.go。GKE 上不想挂载 JSON启用--google-use-application-default-credentials并配合 Workload Identity 绑定无需任何密钥文件。九、相关资源本文核心依据文档v7.9.x Google Provider 文档Google Provider 实现源码providers/google.go 及测试 providers/google_test.goGoogleOptions 配置结构定义pkg/apis/options/providers.goGoogle 配置校验规则pkg/validation/providers.go命令行 Flag 定义pkg/apis/options/legacy_options.go通用配置文件示例contrib/oauth2-proxy.cfg.example【免费下载链接】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），仅供参考