Google 登录配置

Google 登录是 SaaS 产品里最常见的第三方登录方式之一。它适合面向全球用户、企业用户、教育用户、创作者和普通消费者的产品。相比 GitHub 登录Google 登录覆盖的人群更广。但它的配置项也更多Google Cloud 项目、OAuth consent screen、OAuth Client、Authorized redirect URI、scope、ID Token、邮箱验证和账号绑定。本文基于 Google 官方身份和 OAuth 文档整理OpenID ConnectUsing OAuth 2.0 for Web Server Applications第一步创建 Google Cloud 项目接入 Google 登录前你需要先进入 Google Cloud Console创建或选择一个项目。OAuth 客户端、授权同意屏幕、应用名称、重定向地址和密钥都会挂在这个项目下面。如果你的产品有开发、测试、生产多个环境建议提前规划项目和 OAuth Client 的关系。早期可以一个项目里创建多个 OAuth Client也可以不同环境使用不同项目。重点是不要把测试环境和生产环境的配置混在一起否则 callback URL、密钥和用户授权状态会很容易出错。第二步配置 OAuth consent screenGoogle 登录会展示授权同意页面告诉用户哪个应用正在请求登录权限。你需要配置应用名称、支持邮箱、开发者联系方式、应用主页、隐私政策、服务条款等信息。如果只是内部测试可以先使用测试状态和测试用户。但如果要正式开放给外部用户就需要按 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_IDxxx GOOGLE_CLIENT_SECRETxxx GOOGLE_CALLBACK_URLhttps://example.com/api/auth/callback/google不要把 Client Secret 放到前端也不要提交到公开仓库。第五步生成授权 URLGoogle Web Server flow 使用授权码模式。用户点击“使用 Google 登录”后你要把用户跳转到 Google 授权端点。常见参数包括client_id redirect_uri response_typecode scope state access_type prompt登录场景常用 scopeopenid profile emailGoogle 文档说明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 TokenGoogle 登录和普通 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。否则不能把它当作可靠邮箱。如果邮箱未验证或没有返回邮箱你可以提示用户补充邮箱或者要求用户完成额外验证。邮箱是登录、通知、找回账号、支付和团队邀请的基础字段不要随便假设它一定可靠。第十步创建本地 sessionGoogle 登录成功后你的系统应该创建自己的 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 集成教程。原文链接Google 登录配置 | Harries Blog™