返回文章

Cloudflare Workers 接入 Google 登录:从域名验证到外部发布

以 Cloudflare Workers、D1 与 Better Auth 构成的个人博客为例,记录生产环境接入 Google OAuth 2.0 的五个步骤:域名绑定、所有权验证、Google Auth Platform 配置、运行时密钥隔离与正式版发布验收。

给博客接入 Google 登录时,本地跑通 localhost:3000 很容易,线上开放给外部读者则取决于一套跨平台的信任契约:浏览器只负责发起跳转和接收站点 Cookie;Google 校验授权网域与回调地址后,把授权码交给 Cloudflare Worker;Worker 用 Better Auth 换取令牌并在 D1 建立会话。

下面以 blog.example.com(根域 example.com)为例,记录生产环境从域名绑定到外部发布的完整配置。

1. 绑定自定义生产域名

OAuth 回调、Cookie 作用域和 Google 品牌验证都需要稳定的生产 HTTPS 来源,不能使用临时的 *.workers.dev。

在 Cloudflare 将 blog.example.com 绑定到生产 Worker(与 wrangler.jsonc 保持一致)。站点以此地址生成 canonical、RSS 与 Sitemap,旧的 workers.dev 链接通过 308 跳转并保留原路径。

Cloudflare 的自定义域和路由列表中,blog.example.com 已绑定生产 Worker

Cloudflare Workers 自定义域名

2. 验证根域所有权

Google 要求外部 OAuth 应用证明「已获授权的网域」归属。此处必须使用对生产 Google Cloud 项目拥有所有者或编辑者权限的同一个 Google 账号操作,否则 Google Auth Platform 无法关联验证结果。

在 Google Search Console 添加 example.com 网域资源,将生成的 google-site-verification=... 作为 @ 的 TXT 记录写入 Cloudflare DNS。验证通过后保留该 TXT 记录,供 Google 定期复核。

Google Search Console 显示 example.com 的所有权已验证

Google Search Console 所有权验证

3. 配置 Google Auth Platform

在 Google Cloud Console 打开「Google Auth Platform」,依次完成品牌、范围与 Web 客户端配置。

品牌塑造与授权网域

应用首页、隐私政策(/privacy)与服务条款(/terms)必须公开可访问,且归属在已验证的根域 example.com 下。

Google 品牌设置显示首页、隐私政策、服务条款、已获授权的网域与品牌验证状态

数据访问范围

仅勾选 openid、userinfo.email、userinfo.profile 三个非敏感范围。不申请敏感或受限范围,可直接走基础品牌验证,无需额外安全审计。

Google 数据访问页面的三个非敏感范围为 openid、userinfo.email 和 userinfo.profile

Web 客户端与本地隔离

创建 Web 应用客户端时:

  • 已获授权的 JavaScript 来源:留空,授权码由 Worker 在服务端换取。
  • 已获授权的重定向 URI:精确填写 https://blog.example.com/api/auth/callback/google。

Google Web 应用客户端的 JavaScript 来源留空,重定向 URI 指向生产 Google 回调

客户端创建后立即保存一次性显示的密钥,仓库只保留字段名。本地开发单独使用一个测试项目和 Web 客户端,回调仅配 http://localhost:3000/api/auth/callback/google,写入本地 .dev.vars,不与生产客户端混用。

Google OAuth 客户端管理 · Google OAuth 生产政策 · Better Auth Google 提供方

4. 运行时密钥与自动发布

OAuth 凭据属于运行时配置,存放在生产 Worker 的「运行时变量和密钥」中(BETTER_AUTH_URL 设为 https://blog.example.com);Workers Builds 的构建环境只放构建与发布所需的 Cloudflare 凭据,两者分开管理。

Cloudflare Worker 的运行时变量和密钥列表显示 BETTER_AUTH_URL、GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 等名称

核对 Workers Builds 生产配置后,推送 main 触发自动部署(依次执行 pnpm verify && pnpm build 与 pnpm release):

配置项值
GitHub 仓库your-account/personal-blog
生产分支main
构建命令pnpm verify && pnpm build
部署命令pnpm release

Cloudflare Workers 运行时密钥 · Cloudflare Workers Builds 配置

5. 发布正式版与验收

外部应用默认处于「测试版」,仅测试名单内的账号可登录。上线按先内测、后发布的顺序验收:

  1. 测试态闭环:用测试名单内的账号从文章页发起 Google 登录,验证授权后跳回原文,以及收藏、取消收藏和退出;再用 GitHub 登录交叉验证。
  2. 切为正式版:在「目标对象」将应用发布为「正式版」,并在「验证中心」提交品牌验证。
  3. 外部账号终验:换一个未加入测试名单的外部 Google 账号走完登录与收藏,确认退出后收藏写接口拒绝未登录请求。

Google Auth Platform 目标对象页面显示发布状态为正式版、用户类型为外部

生产登录页上的「使用 Google 登录」和「使用 GitHub 登录」按钮

Google 应用受众 · Google 品牌验证

常见错误速查

现象核对项
Google 显示 redirect_uri_mismatch核对生产客户端 ID,将重定向 URI 与 /api/auth/callback/google 逐字比对
Worker 回调后退回登录页核对 Worker Secret 的 ID 与密钥来自同一客户端;查看 Worker 日志,从正式域名重新发起登录以刷新 OAuth state
外部用户无法授权在「目标对象」核对是否已切为正式版,在「验证中心」检查品牌或授权域状态
域名访问返回证书错误核对 Cloudflare 区域激活状态、Worker 自定义域名绑定与证书签发状态
更换 Google 客户端密钥先在 Google 客户端新增密钥,更新生产 Worker Secret 并登录验收通过后,再撤销旧密钥

参考资料

  1. Cloudflare Workers 自定义域名
  2. Google Search Console 所有权验证
  3. Google OAuth 客户端管理
  4. Google OAuth 生产政策
  5. Better Auth Google 提供方
  6. Cloudflare Workers 运行时密钥
  7. Cloudflare Workers Builds 配置
  8. Google 应用受众
  9. Google 品牌验证