Google 登录配置

Google 登录是 SaaS 产品里最常见的第三方登录方式之一。它适合面向全球用户、企业用户、教育用户、创作者和普通消费者的产品。

相比 GitHub 登录，Google 登录覆盖的人群更广。但它的配置项也更多：Google Cloud 项目、OAuth consent screen、OAuth Client、Authorized redirect URI、scope、ID Token、邮箱验证和账号绑定。

本文基于 Google 官方身份和 OAuth 文档整理：

• OpenID Connect
• Using OAuth 2.0 for Web Server Applications

第一步：创建 Google Cloud 项目

接入 Google 登录前，你需要先进入 Google Cloud Console，创建或选择一个项目。

OAuth 客户端、授权同意屏幕、应用名称、重定向地址和密钥，都会挂在这个项目下面。

如果你的产品有开发、测试、生产多个环境，建议提前规划项目和 OAuth Client 的关系。早期可以一个项目里创建多个 OAuth Client，也可以不同环境使用不同项目。

重点是不要把测试环境和生产环境的配置混在一起，否则 callback URL、密钥和用户授权状态会很容易出错。

第二步：配置 OAuth consent screen

Google 登录会展示授权同意页面，告诉用户哪个应用正在请求登录权限。

你需要配置应用名称、支持邮箱、开发者联系方式、应用主页、隐私政策、服务条款等信息。

如果只是内部测试，可以先使用测试状态和测试用户。但如果要正式开放给外部用户，就需要按 Google 要求完成必要配置。

同意屏幕不是装饰，它会影响用户是否信任你的产品。应用名称、域名和说明要保持一致。

第三步：创建 OAuth Client ID

进入 APIs & Services 下的 Credentials，创建 OAuth client ID。

应用类型选择 Web application。然后配置：

Name：客户端名称，比如 Production Web
Authorized JavaScript origins：你的站点来源
Authorized redirect URIs：你的 OAuth 回调地址

示例：

Authorized JavaScript origins:
https://example.com

Authorized redirect URIs:
https://example.com/api/auth/callback/google

开发环境可以添加：

http://localhost:3000
http://localhost:3000/api/auth/callback/google

注意：Google 官方文档强调，授权请求里的 redirect_uri 必须和 Cloud Console 中配置的 Authorized redirect URI 精确匹配，包括协议、大小写、路径和尾部斜杠。

第四步：保存 Client ID 和 Client Secret

创建 OAuth Client 后，你会拿到 Client ID 和 Client Secret。

和其他 OAuth 平台一样：

Client ID：用于生成授权请求
Client Secret：只放服务端，用于 code 换 token

建议放在环境变量里：

GOOGLE_CLIENT_ID=xxx
GOOGLE_CLIENT_SECRET=xxx
GOOGLE_CALLBACK_URL=https://example.com/api/auth/callback/google

不要把 Client Secret 放到前端，也不要提交到公开仓库。

第五步：生成授权 URL

Google Web Server flow 使用授权码模式。用户点击"使用 Google 登录"后，你要把用户跳转到 Google 授权端点。

常见参数包括：

client_id
redirect_uri
response_type=code
scope
state
access_type
prompt

登录场景常用 scope：

openid profile email

Google 文档说明，OpenID Connect 登录的 scope 必须以 openid 开头，再按需包含 profile 和 email。

state 用于防伪和关联请求，应该在发起登录时保存，并在回调时校验。

第六步：处理回调并换 token

用户授权后，Google 会跳回你的 redirect URI，并带上 code 和 state。

你的服务端要先校验 state，然后用 code 换 token。

换 token 时会拿到一些重要字段，通常包括 access token 和 ID token。对登录来说，ID token 非常关键，因为它代表用户身份声明。

注意：code 换 token 必须在服务端完成，因为这个过程需要 Client Secret。

第七步：验证 ID Token

Google 登录和普通 OAuth 授权不同的一点，是它基于 OpenID Connect，可以通过 ID Token 获取用户身份。

你不能只拿到 ID Token 就直接相信它。服务端应该验证：

签名是否有效
iss 是否是 Google
aud 是否等于你的 Client ID
exp 是否未过期
nonce / state 是否符合你的流程

很多成熟认证库会帮你做这些校验。不要自己随意解析 JWT 后就当作可信身份。

第八步：使用 sub 绑定本地用户

Google 返回的用户唯一标识通常是 sub。它比邮箱更适合作为 provider user id。

本地账号绑定表可以这样设计：

user_id
provider = google
provider_user_id = sub
provider_email = email
email_verified = true / false
created_at
updated_at

不要只用邮箱做唯一绑定。邮箱可能变化，也可能涉及企业域名、别名或已有账号冲突。

使用 sub 作为第三方账号标识，会更稳妥。

第九步：确认邮箱是否已验证

Google 返回的身份信息里通常会有 email 和 email_verified。

如果你的产品依赖邮箱作为重要身份信息，要确认 email_verified 为 true。否则不能把它当作可靠邮箱。

如果邮箱未验证，或没有返回邮箱，你可以提示用户补充邮箱，或者要求用户完成额外验证。

邮箱是登录、通知、找回账号、支付和团队邀请的基础字段，不要随便假设它一定可靠。

第十步：创建本地 session

Google 登录成功后，你的系统应该创建自己的 session 或 cookie。

不要把 Google access token 当作你产品内的登录态。access token 是访问 Google API 的凭证，不是你的应用 session。

如果你只是做登录，不需要长期保存 Google access token。如果你还要访问 Google Drive、Calendar 等 API，再根据权限和业务需要保存 token，并处理刷新、撤销和加密。

常见错误检查

Google 登录失败时，优先检查：

redirect_uri 是否和 Cloud Console 精确一致
是否选择了 Web application 类型
OAuth consent screen 是否配置完整
scope 是否包含 openid profile email
state 是否正确保存和校验
code 换 token 是否在服务端完成
ID Token 是否正确验证
是否使用 sub 绑定本地用户
email_verified 是否检查
是否创建了本地 session

其中最常见的问题，是 redirect_uri_mismatch。遇到它时，直接回到 Cloud Console 对照协议、域名、路径和尾部斜杠。

写在最后

Google 登录覆盖面广，但也更强调配置准确性和身份验证严谨性。

一个稳妥的 Google 登录流程，应该做到：Cloud 项目清楚、同意屏幕可信、redirect URI 精确匹配、scope 最小化、state 校验、ID Token 验证、sub 绑定、本地 session 创建。

下一篇，我们继续进入支付模块：Stripe 集成教程。