跳到主要内容

设置 Google 社交登录

集成 Google OAuth 2.0 认证 (Authentication) 系统，实现 Google 登录、账户关联以及安全访问 Google API。

提示:

本指南假设你对 Logto 连接器 (Connectors) 有基本的了解。对于不熟悉的人，请参考 连接器 (Connectors) 指南以开始了解。

开始使用​

Google 连接器 (Connector) 支持 OAuth 2.0 集成，让你的应用可以：

  • 添加“使用 Google 登录”认证 (Authentication)
  • 将用户账户与 Google 身份关联
  • 从 Google 同步用户资料信息
  • 通过 Logto Secret Vault 安全存储令牌访问 Google API，实现自动化任务（如在你的应用中编辑 Google Docs、管理日历事件等）

要设置这些认证 (Authentication) 功能，首先需要在 Logto 创建一个 Google 连接器 (Connector)：

  1. 前往 Logto 控制台 > 连接器 (Connector) > 社交连接器 (Connector)。
  2. 点击 添加社交连接器 (Connector)，选择 Google，点击 下一步，并按照分步教程完成集成。

第一步：在 Google Auth Platform 创建项目​

在你使用 Google 作为认证 (Authentication) 提供商之前，必须在 Google Cloud Console 中设置一个项目以获取 OAuth 2.0 凭据。如果你已经有项目，可以跳过此步骤。

  1. 访问 Google Cloud Console，并使用你的 Google 账号登录。
  2. 点击顶部菜单栏的 选择项目 按钮，然后点击 新建项目 按钮来创建一个项目。
  3. 在你新创建的项目中，进入 API 和服务 > OAuth 用户授权页面 配置你的应用：
    • 应用信息：输入将在用户授权页面显示的 应用名称 和 支持邮箱
    • 受众 (Audience)：选择你偏好的受众类型：
      • 内部 - 仅限你组织内的 Google Workspace 用户
      • 外部 - 面向所有 Google 用户（生产环境需通过验证）
    • 联系信息：填写邮箱地址，以便 Google 通知你项目的任何变更
    • 勾选 我同意 Google 的政策 完成基础设置
  4. 可选，前往 品牌 部分编辑产品信息并上传你的 应用 Logo，该 Logo 会显示在 OAuth 用户授权页面，帮助用户识别你的应用。
提示:

如果你选择了 外部 受众类型，开发期间需要添加测试用户，生产环境需发布你的应用。

第二步：创建 OAuth 2.0 凭据​

在 Google Cloud Console 的 凭据 页面为你的应用创建 OAuth 凭据。

  1. 点击 创建凭据 > OAuth 客户端 ID。
  2. 选择 Web 应用 作为应用类型。
  3. 填写 OAuth 客户端的 名称。该名称仅用于识别凭据，不会显示给终端用户。
  4. 配置授权的 URI：
    • 授权的 JavaScript 来源：添加你的 Logto 实例的来源（如 https://your-logto-domain.com）
    • 授权的重定向 URI：添加 Logto 的 回调 URI（可从 Logto Google 连接器中复制）
  5. 点击 创建 生成 OAuth 客户端。

第三步：用凭据配置 Logto 连接器​

创建 OAuth 客户端后，Google 会弹出一个包含你凭据的窗口：

  1. 复制 Client ID 并粘贴到 Logto 的 clientId 字段
  2. 复制 Client secret 并粘贴到 Logto 的 clientSecret 字段
  3. 在 Logto 中点击 保存并完成，将你的身份系统与 Google 连接
注意:

请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即生成新的。

第四步：配置权限 (Scopes)​

权限 (Scopes) 定义了你的应用向用户请求的权限，并控制你的应用可以访问他们 Google 账户中的哪些数据。

在 Google Cloud Console 配置权限 (Scopes)​

  1. 进入 API 和服务 > OAuth 用户授权页面 > 权限 (Scopes)。
  2. 点击 添加或移除权限，只选择你的应用所需的权限：
    • 认证 (Authentication)（必需）：
      • https://www.googleapis.com/auth/userinfo.email
      • https://www.googleapis.com/auth/userinfo.profile
      • openid
    • API 访问（可选）：根据你的应用需求添加额外权限（如 Drive、Calendar、YouTube）。浏览 Google API Library 查找可用服务。如果你的应用需要访问除基础权限外的 Google API，请先在 Google API Library 启用相应 API（如 Google Drive API、Gmail API、Calendar API）。
  3. 点击 更新 确认选择。
  4. 点击 保存并继续 应用更改。

在 Logto 中配置权限 (Scopes)​

根据你的需求选择以下一种或多种方式：

方式一：无需额外 API 权限

  • 在 Logto Google 连接器的 Scopes 字段留空。
  • 默认会请求 openid profile email 权限，确保 Logto 能正确获取基础用户信息。

方式二：登录时请求额外权限

  • 在 Scopes 字段输入所有需要的权限，使用空格分隔。
  • 你在此处填写的权限会覆盖默认值，因此请务必包含认证 (Authentication) 权限：https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid。
  • 使用完整的权限 URL。例如：https://www.googleapis.com/auth/calendar.readonly。

方式三：后续按需增量请求权限

  • 用户登录后，你可以通过重新发起联合社交授权 (Authorization) 流程并更新用户的令牌集，按需请求额外权限。
  • 这些额外权限无需在 Logto Google 连接器的 Scopes 字段中填写，可通过 Logto 的 Social Verification API 实现。

按照这些步骤，Logto Google 连接器只会请求你的应用所需的权限——不多也不少。

提示:

如果你的应用请求这些权限以访问 Google API 并执行操作，请确保在 Logto Google 连接器中启用 为持久 API 访问存储令牌。详见下一节。

第五步：自定义认证 (Authentication) 提示​

在 Logto 中配置 Prompts，以控制用户认证 (Authentication) 体验。Prompts 是一个字符串数组，指定所需的用户交互类型：

  • none - 授权服务器不会显示任何认证 (Authentication) 或用户授权页面。如果用户尚未认证 (Authentication) 且未预先授权所请求权限，则返回错误。用于检查现有认证 (Authentication) 和 / 或授权。
  • consent - 授权服务器在向客户端返回信息前提示用户授权。启用 Google API 离线访问（offline access）时必需。
  • select_account - 授权服务器提示用户选择一个账户。适用于拥有多个 Google 账户的用户选择用于认证 (Authentication) 的账户。

第六步：常规设置​

以下是一些不会阻止与 Google 连接但可能影响终端用户认证 (Authentication) 体验的常规设置。

同步资料信息​

在 Google 连接器中，你可以设置同步资料信息（如用户名和头像）的策略。可选项包括：

  • 仅在注册时同步：用户首次登录时获取一次资料信息。
  • 每次登录时同步：每次用户登录时都会更新资料信息。

存储令牌以访问 Google API（可选）​

如果你希望访问 Google API 并在用户授权下执行操作（无论是通过社交登录还是账户绑定），Logto 需要获取特定 API 权限并存储令牌。

  1. 在 Google Cloud Console 的 OAuth 用户授权页面配置和 Logto Google 连接器中添加所需权限。
  2. 在 Logto Google 连接器中启用 为持久 API 访问存储令牌。Logto 会将 Google 访问令牌和刷新令牌安全地存储在 Secret Vault 中。
  3. 为确保返回刷新令牌，请按如下方式配置 Logto Google 连接器：
    • 设置 Prompts 包含 consent
    • 启用 离线访问
注意:

你无需在 Logto 的 Scope 字段中添加 offline_access —— 添加可能导致错误。Google 在启用离线访问时会自动使用 access_type=offline。

第七步：启用 Google One Tap（可选）​

Google One Tap 是一种安全且简便的方式，让用户通过弹窗界面用 Google 账号登录你的网站。

当你设置好 Google 连接器后，会在连接器详情页看到 Google One Tap 的卡片。切换开关即可启用 Google One Tap。

Google One Tap 配置选项​

  • 如有可能自动选择凭据 - 如果 满足特定条件，自动用 Google 账号登录用户
  • 用户点击 / 触摸弹窗外部时取消提示 - 如果用户点击或触摸弹窗外部，则关闭 Google One Tap 提示。若禁用，用户需点击关闭按钮才能关闭提示。
  • 在 ITP 浏览器上启用升级版 One Tap 体验 - 在智能跟踪防护 (ITP) 浏览器上启用升级版 Google One Tap 用户体验。详见 官方文档。
注意:

请确保在 OAuth 客户端配置的 授权的 JavaScript 来源 部分添加你的域名，否则 Google One Tap 无法显示。

Google One Tap 的重要限制​

如果你同时启用了 为持久 API 访问存储令牌 和 Google One Tap，你不会自动获得访问令牌或所请求的权限。

Google One Tap 登录（不同于标准的“使用 Google 登录”按钮）不会颁发 OAuth 访问令牌。它只返回一个 ID 令牌（签名的 JWT），用于验证用户身份，但不授予 API 访问权限。

要让 Google One Tap 用户访问 Google API，你可以在用户用 Google One Tap 登录后，通过 Logto 的 Social Verification API 重新发起联合社交授权 (Authorization) 流程。这允许你按需请求额外权限并更新用户的令牌集，无需在 Logto Google 连接器中预先填写这些权限。这种方式实现了增量授权 (Authorization)，只有当你的应用真正需要时，用户才会被提示额外权限。

详细了解 Google One Tap 的限制 可参考官方文档。

第八步：测试并发布你的应用​

针对内部应用​

如果你在 Google 中的 受众 (Audience) 类型设置为 内部，你的应用只对你组织内的 Google Workspace 用户可用。你可以用组织内的任意账号进行测试。

针对外部应用​

如果你的 受众 (Audience) 类型为 外部：

  1. 开发期间：进入 OAuth 用户授权页面 > 测试用户，添加测试用户邮箱地址。只有这些用户可以登录你的应用。
  2. 生产环境：在 OAuth 用户授权页面部分点击 发布应用，让所有拥有 Google 账号的用户都能使用。
备注:

具有敏感或受限权限的应用在发布前可能需要 Google 审核。此过程可能需要数周时间。

使用 Google 连接器 (Connector)​

创建并连接好 Google 连接器 (Connector) 后，你可以将其集成到终端用户流程中。根据你的需求选择合适的选项：

启用“使用 Google 登录”​

  1. 在 Logto 控制台，前往 登录体验 > 注册与登录。
  2. 在 社交登录 部分添加 Google 连接器 (Connector)，让用户可以通过 Google 认证 (Authentication)。
  3. 可选：在登录和注册页面启用 Google One Tap，为用户提供更流畅的认证 (Authentication) 体验。

了解更多关于社交登录体验。

使用 Account API 在你的应用中构建自定义账户中心，让已登录用户可以关联或解除关联他们的 Google 账户。参考 Account API 教程

提示:

你可以只为账户关联和 API 访问启用 Google 连接器 (Connector)，而不启用社交登录。

访问 Google API 并执行操作​

你的应用可以从 Secret Vault 获取存储的 Google 访问令牌 (Access token)，调用 Google API 并自动化后端任务（例如管理 Google Drive 文件、创建日历事件或通过 Gmail 发送邮件）。参考相关指南获取用于 API 访问的存储令牌。

管理用户的 Google 身份​

用户关联 Google 账户后，管理员可以在 Logto 控制台管理该连接：

  1. 前往 Logto 控制台 > 用户管理 并打开该用户的资料页。
  2. 在 社交连接 下找到 Google 项，点击 管理。
  3. 在此页面，管理员可以管理用户的 Google 连接，查看所有从 Google 账户授权并同步的资料信息，以及检查访问令牌 (Access token) 状态。

参考资料​

Google 身份：设置 OAuth 2.0

Google 身份服务（One Tap）

 Google Cloud 控制台