EN

Google OAuth 配置

本指南将帮助您为应用配置 Google OAuth。完成配置后，用户即可使用 Google 账号登录。

前置条件

步骤 1：创建 Google Cloud 项目

  1. 打开 Google Cloud 控制台
  2. 点击页面顶部的项目下拉菜单
  3. 点击 新建项目
  4. 输入项目名称（如「MyApp OAuth」）
  5. 点击 创建

提示： 使用具有描述性的项目名称，便于后续管理。

步骤 2：启用所需 API

  1. 在 Google Cloud 控制台中，进入 API 和服务 > 库
  2. 搜索「Google Identity」或「People API」
  3. 点击 Google Identity Services（或旧的 Google+ API）并 启用
  4. 对于基本的 OAuth 2.0 流程，配置 OAuth 同意屏幕和凭据即可，email/profile 等 scope 无需额外启用 API

步骤 3：配置 OAuth 同意屏幕

  1. 进入 API 和服务 > OAuth 同意屏幕
  2. 选择 外部 用户类型（使用 Google Workspace 时可选内部）
  3. 点击 创建
  4. 填写必填信息：
字段 说明 示例
应用名称 您的应用名称 MyApp
用户支持电子邮件 面向用户的联系邮箱 support@myapp.com
应用徽标 应用图标（可选） -
应用网域 您的网站域名 myapp.com
开发者联系邮箱 您的邮箱 dev@myapp.com
  1. 点击 保存并继续

添加范围

  1. 点击 添加或删除范围
  2. 选择以下范围：
  • email - 查看用户邮箱地址
  • profile - 查看用户基本资料
  • openid - 使用 OpenID Connect 认证
  1. 点击 更新
  2. 点击 保存并继续

步骤 4：创建 OAuth 凭据

  1. 进入 API 和服务 > 凭据
  2. 点击 创建凭据 > OAuth 客户端 ID
  3. 选择应用类型：

Web 应用

  • 应用类型：Web 应用
  • 名称：「MyApp Web Client」
  • 已授权的 JavaScript 来源：
https://yourdomain.com
  http://localhost:3000 （开发用）
  • 已授权的重定向 URI：
https://yourdomain.com/auth/google/callback
  http://localhost:3000/auth/google/callback

iOS 应用

  • 应用类型：iOS
  • 名称：「MyApp iOS Client」
  • 套装 ID：com.yourcompany.myapp

Android 应用

  • 应用类型：Android
  • 名称：「MyApp Android Client」
  • 软件包名称：com.yourcompany.myapp
  • SHA-1 证书指纹：（您的签名证书）
  1. 点击 创建
  2. 保存 客户端 ID 和 客户端密钥

重要： 请妥善保管客户端密钥，切勿在客户端代码中暴露。

步骤 5：在 OpenDev 中配置

将 Google OAuth 凭据配置到 OpenDev：

  1. 登录 OpenDev 平台
  2. 进入 OAuth 渠道
  3. 点击 添加 OAuth 渠道 或编辑已有 Google 渠道
  4. 填写配置：
{
  "provider": "google",
  "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "scopes": ["email", "profile", "openid"],
  "callbackUrl": "https://yourdomain.com/auth/google/callback"
}

配置字段

字段 必填 说明
Client ID 是 来自 Google 控制台的 OAuth 2.0 客户端 ID
Client Secret 是 OAuth 2.0 客户端密钥
Scopes 是 请求的权限范围
Callback URL 是 您已授权的重定向 URI

步骤 6：测试集成

  1. 在应用中触发 Google OAuth 流程
  2. 应能看到 Google 登录页面
  3. 授权后将被重定向回并携带用户数据

OAuth 响应示例

{
  "provider": "google",
  "providerId": "123456789",
  "email": "user@gmail.com",
  "name": "John Doe",
  "avatar": "https://lh3.googleusercontent.com/..."
}

故障排查

错误：redirecturimismatch

请求中的重定向 URI 与任一已授权的 URI 不匹配。

解决： 将确切的重定向 URI 添加到 Google Cloud 控制台凭据中。

错误：invalid_client

未找到 OAuth 客户端或凭据有误。

解决： 确认 Client ID 和 Client Secret 正确无误。

错误：access_denied

用户拒绝了授权请求。

解决： 当用户点击「取消」时属正常行为。

最佳实践

  1. 生产环境使用 HTTPS，所有重定向 URI 均需 HTTPS
  2. 验证 state 参数，防止 CSRF 攻击
  3. 安全存储令牌，使用加密
  4. 实现令牌刷新，以支持长会话
  5. 妥善处理错误，提供友好的错误提示

相关文档