oauth2-proxy 接入 Google 身份提供商应用注册、群组鉴权与 ADC/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-proxyGoogle 是 oauth2-proxy 的默认身份提供商Identity Provider本文以官方文档 Google (default) 为主线完整讲解从 Google Cloud 注册 OAuth 应用、配置 oauth2-proxy到可选的 Google 群组登录限制与 ADC/Workload Identity 凭证体系的全部步骤并结合仓库源码providers/google.go、providers/google_test.go剖析其端点默认值、组校验与令牌刷新机制。读完本文你将能在生产环境中独立完成 Google 登录的接入、按群组做细粒度授权以及让服务账号凭证以最安全的方式被使用。一、为什么 Google 是默认提供商oauth2-proxy 在未显式指定--provider时默认采用 Google。这一事实在源码中有两处直接证据在 legacy_options.go 中--provider标志的默认值即为googleflagSet.String(provider, google, OAuth provider)在 providers.gooptions 包 的providerDefaults()中默认构造的 Providers 列表首项即Type: google。同时版本化 providers 索引文档 明确将 Google 标记为_default_。从源码 google.go 的NewGoogleProvider可以看到当没有任何 Google 专属配置时setProviderDefaults会填入如下内置端点与 Scope项目默认值说明登录端点LoginURLhttps://accounts.google.com/o/oauth2/auth?access_typeoffline附带access_typeoffline用于获取 refresh token令牌兑换端点RedeemURLhttps://www.googleapis.com/oauth2/v3/token用授权码换 access/refresh/id token校验端点ValidateURLhttps://www.googleapis.com/oauth2/v1/tokeninfo访问令牌校验ProfileURL空Google 不额外使用 profile 端点Scopeprofile email默认申请的基础权限这些默认值由测试 TestNewGoogleProvider 断言锁定测试期望 ProviderName 为Google并精确匹配上述四个 URL 与profile email的 Scope。也就是说只要提供 Client ID 与 Client Secretoauth2-proxy 即可开箱即用地对接 Google 的 OAuth 2.0 服务。二、Google 专属配置项全览官方文档给出了一张配置表以下按Flag / TOML 字段 / 类型 / 说明 / 默认值完整列出version-7.11.x 共 5 项另有 2 项在更新版本文档中新增见下文FlagToml Field类型说明默认值--google-admin-emailgoogle_admin_emailstring用于调用 Google Admin API 时代理impersonate的管理员邮箱空--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空/false--google-target-principalgoogle_target_principalstring使用 ADC 时所要模拟的目标主体principal默认为 ADC 所配置的服务账号以上字段在 legacy_options.go 中均以flag/cfg双标签定义因此在命令行 Flag 与 TOML 配置文件中可等价使用。对应的结构化 Go 定义为 providers.go 中的GoogleOptions其 YAML 字段用于 Alpha Config为group、adminEmail、serviceAccountJson、useApplicationDefaultCredentials、targetPrincipal另有useOrganizationID与adminAPIUserScope。更新版本新增的两项可选配置在仓库当前文档 docs/docs/configuration/providers/google.md 中配置表扩充了以下两项源码 legacy_options.go 亦已支持FlagToml Field类型说明默认值--google-use-organization-idgoogle_use_organization_idbool使用组织 ID 作为 preferred usernamefalse--google-admin-api-user-scopegoogle_admin_api_user_scopestring查询 Google Admin SDK 获取组织 ID 时使用的 OAuth scope可为readonly、user或cloudreadonly默认情况下Google 提供商以 Google IDsub声明作为用户名若希望改用组织 ID可设置--google-use-organization-idtrue此时要求第 5 步中授予 Admin SDK 的服务账号具备下列 scope 之一https://www.googleapis.com/auth/admin.directory.user.readonlyhttps://www.googleapis.com/auth/admin.directory.userhttps://www.googleapis.com/auth/cloud-platform源码 getAdminAPIUserScope 展示了readonly/user/cloud三种取值到实际 OAuth scope 的映射cloud对应CloudPlatformScopeuser对应AdminDirectoryUserScope其余含默认对应AdminDirectoryUserReadonlyScope。三、在 Google Cloud 中注册 OAuth 应用官方步骤按官方文档为 Google 完成应用注册的步骤如下在此只以文字描述操作路径请登录 Google Cloud Console 操作新建一个项目在 Google Cloud Console 的项目创建页面完成。如果当前选中了其他项目从右上角项目下拉框切换到刚创建的新项目。在项目 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 时使用。官方文档建议使用短周期1 小时的cookie-refresh设置来刷新会话这样可以在每个刷新周期验证账号是否仍被授权。--cookie-refresh属于 oauth2-proxy 的通用会话配置其语义在 sessions.md 中有说明它控制代理尝试刷新 Access Token 的间隔若 Access Token 过期且未设置对应的cookie-refresh通常会遭遇 401 并重新引导用户登录因此建议将cookie-refresh设置为略短于 Access Token 生命周期的值。overview.md 也确认 Google 属于支持--cookie-refresh的提供商之一。四、最小可用配置命令行、TOML 与 Alpha Config 三种写法注册完 OAuth 应用后即可配置 oauth2-proxy。以下给出 Google 场景下的三种等价配置形态。命令行 Flag 方式./oauth2-proxy \ --providergoogle \ --client-id1234567890-xxxxxxxx.apps.googleusercontent.com \ --client-secretGOCSPX-XXXXXXXXXXXXXXXXXXXXXXXX \ --redirect-urlhttps://internal.yourcompany.com/oauth2/callback \ --email-domainyourcompany.com \ --cookie-secretXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \ --cookie-refresh1h \ --http-address0.0.0.0:4180 \ --upstreamhttp://127.0.0.1:8080其中--client-id的格式参考了 contrib/oauth2-proxy.cfg.example 中的注释123456.apps.googleusercontent.com。--redirect-url必须与第 6 步中登记的 Authorized redirect URI 完全一致。--email-domainyourcompany.com用于限定允许登录的邮箱域名来自 providers 索引文档 的 Email Authentication 一节若想允许所有邮箱可改用--email-domain*。TOML 配置文件方式将 Flag 一一对应为 TOML 字段字段名即上表第二列provider google client_id 1234567890-xxxxxxxx.apps.googleusercontent.com client_secret GOCSPX-XXXXXXXXXXXXXXXXXXXXXXXX redirect_url https://internal.yourcompany.com/oauth2/callback email_domain [yourcompany.com] cookie_secret XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX cookie_refresh 1h http_address 0.0.0.0:4180 upstream [http://127.0.0.1:8080]Alpha ConfigYAML方式在 Alpha Config 中Google 专属参数收敛到providers[].googleConfig结构下字段名对应 GoogleOptions 的 YAML 标签providers: - id: google provider: google clientID: 1234567890-xxxxxxxx.apps.googleusercontent.com clientSecret: GOCSPX-XXXXXXXXXXXXXXXXXXXXXXXX googleConfig: adminEmail: adminyourcompany.com group: [team-coreyourcompany.com] serviceAccountJson: /etc/oauth2-proxy/google-service-account.json三种写法最终都会归一化到同一套GoogleOptions并由 providers 包 的New()根据provider类型分发到NewGoogleProvider。五、限制登录到指定 Google 群组可选如果希望只有特定 Google 群组成员才能访问受保护资源官方文档给出了完整的配置路径。整体前提是群组校验依赖 Google Admin SDK因此必须有一个具备相应权限的服务账号或默认凭证与一个管理员邮箱。操作步骤创建服务账号并将其配置为使用 ADC / Workload Identity / Workload Identity Federation推荐或者直接下载 JSON 凭证文件。记下该服务账号的 Client ID后续步骤会用到。在 APIs Auth 下选择 APIs。找到Admin SDK并启用该 API。按照 Google 官方的为服务账号设置域范围委派domain-wide delegation步骤把第 2 步的 Client ID 授予如下 OAuth scopehttps://www.googleapis.com/auth/admin.directory.group.member.readonly按照 Google 帮助文档support.google.com/a中关于启用 Admin API 访问权限的条目启用 Admin API 访问。在 Gmail 域中创建或选择一个管理员邮箱地址赋给--google-admin-email标志。该邮箱将由客户端模拟impersonate去调用 Admin SDK这也是第 5 步委派操作的原因。创建或选择一个已有的邮箱群组将其地址赋给--google-group标志。该标志可以多次指定不同群组用户会被逐一检查是否属于其中任意一个群组。仅在使用 JSON 文件即第 1 步选择下载 JSON时还需继续第 9、10 步收紧第 1 步下载的 JSON 文件权限确保只有 oauth2-proxy 能读取该文件并将文件路径配置到--google-service-account-json标志。重启 oauth2-proxy 使配置生效。群组校验时机与源码机制官方文档特别提示用户会在初始认证以及每次令牌刷新约每小时一次时被重新核对群组成员身份。这在源码中有完整对应实现configureGroups / setGroupRestriction当配置了--google-group时groupValidator会对每个群组调用userInGroup并把命中的群组写入session.Groups只有至少命中一个群组才返回true。userInGroup优先使用 Admin Directory 的HasMemberAPI可识别嵌套子群组。若返回 404群组不存在或 400典型场景用户邮箱与群组不在同一域例如群组groupmydomain.com中的memberotherdomain.com则会回退到直接查询该群组的成员对象并额外校验成员状态必须为ACTIVEARCHIVED、SUSPENDED、UNKNOWN一律不算。populateAllGroups与表格中未指定群组且配置了服务账号/默认凭证时允许所有用户群组的说明对应——此时 oauth2-proxy 会通过 getUserGroups 分页拉取用户所属的全部群组写入会话并始终放行即使拉取失败也放行仅记录错误日志。刷新时的复检在 RefreshSession 中完成刷新令牌后若groupValidator返回false刷新失败并返回%s is no longer in the group(s)错误。以上行为均有对应测试覆盖详见 TestGoogleProvider_userInGroup覆盖同域成员、跨域成员的 HasMember 命中与 400 回退路径与 TestGoogleProvider_getUserGroups验证分页群组列表解析。六、使用应用默认凭证ADC/ Workload Identity / Workload Identity Federation推荐在 GCP 内部署时与其手动下载并维护服务账号 JSON 文件官方文档推荐使用Application Default Credentials应用默认凭证ADC部署在 GCP 内oauth2-proxy 可以自动使用挂载到资源上的服务账号。部署在 GKE 时ADC 可通过Workload Identity功能启用按 Google 官方 Workload Identity 指南配置即可。部署在 GCP 外可以考虑使用Workload Identity Federation工作负载身份联合。从源码看ADC 的实际落地逻辑位于 getOauth2TokenSource 与 getTargetPrincipal当--google-use-application-default-credentialstrue时oauth2-proxy 通过impersonate.CredentialsTokenSource构造凭证源并以--google-target-principal指定的目标主体TargetPrincipal执行模拟Subject取--google-admin-email若未显式指定--google-target-principalgetTargetPrincipal 会尝试自动判定先读取 ADC JSON 中的client_email若在 GCE 实例上运行则回退调用 GCE metadata 服务获取服务账号邮箱无法判定时以 Fatal 错误退出并提示改用--target-principal覆盖。若未启用 ADC则读取--google-service-account-json指向的 JSON以google.JWTConfigFromJSON加载服务账号私钥并设置conf.Subject opts.AdminEmail实现域范围模拟。此外getAdminService 会按possibleScopesList4 个 Admin Directory 相关 scope逐个尝试获取令牌跳过返回unauthorized_client的 scope若全部失败则以 Fatal 退出并提示google credentials do not have enough permissions to access admin API scope。这意味着群组/组织功能只有在服务账号确实被授予 Admin API scope 时才会生效。七、认证与刷新生命周期源码视角理解 Google 提供商在 oauth2-proxy 内部的工作方式有助于排查为何某用户无法登录/掉线类问题授权码兑换RedeemRedeemgoogle.go向https://www.googleapis.com/oauth2/v3/token提交grant_typeauthorization_code、code、redirect_uri及可选的 PKCEcode_verifier从响应中取出access_token、refresh_token、id_token、expires_in。ID Token 声明解析claimsFromIDToken 对id_token的第二段做 base64 解码得到sub、email、email_verified若缺少email或邮箱未验证email_verified ! true则直接报错。测试 TestGoogleProviderGetEmailAddress 与 TestGoogleProviderGetEmailAddressInvalidJson 分别验证了成功与失败路径。会话充实EnrichSessionEnrichSessiongoogle.go调用groupValidator填充session.Groups并在启用组织 ID 时通过 getUserInfo 从 Admin Directory 的Users.Get响应中提取类型为organization的externalIds值作为 preferred username对应测试 TestGoogleProvider_getUserInfo。令牌刷新RefreshSessionredeemRefreshTokengoogle.go以grant_typerefresh_token换取新的 access/id token随后重新执行群组校验见第五节。八、总结在 oauth2-proxy 中接入 Google 身份提供商核心路径可归纳为在 Google Cloud 注册 Web 应用 → 用--providergoogle Client ID/Secret 配置 →可选配置服务账号 管理员邮箱 --google-group实现群组授权 →推荐用 ADC/Workload Identity 替代 JSON 凭证 → 设置 1 小时左右的cookie-refresh保证授权状态持续有效。若需要进一步对照配置总览可查阅 configuration/overview.md若需要了解所有支持的身份提供商清单可查阅 providers 索引。本文所涉源码与测试均可直接在仓库的 providers/google.go 与 providers/google_test.go 中继续深入阅读。【免费下载链接】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），仅供参考