设置

在向网站添加“使用 Google 帐号登录”功能、“一键登录”或“自动登录”功能之前,请先设置 OAuth 配置,并视需要配置您的网站内容安全政策。

获取您的 Google API 客户端 ID

如需在您的网站上启用“使用 Google 帐号登录”功能,您首先需要设置 Google API 客户端 ID。为此,请完成以下步骤:

  1. 打开 Google API 控制台中的凭据页面。
  2. 创建或选择 Google API 项目。如果您已有用于“使用 Google 帐号登录”按钮或 Google 一键登录的项目,请使用现有项目和 Web 客户端 ID。创建生产应用时,可能需要多个项目,请为您管理的每个项目重复本部分的其余步骤。
  3. 点击创建凭据 > OAuth 客户端 ID,对于应用类型,选择 Web 应用以创建新的客户端 ID。如需使用现有客户端 ID,请选择 Web 应用类型之一。
  4. 将您网站的 URI 添加到已获授权的 JavaScript 来源中。URI 仅包含架构和完全限定的主机名。例如 https://www.example.com

  5. (可选)通过重定向到您托管的端点(而不是通过 JavaScript 回调)返回凭据。如果是这种情况,请将您的重定向 URI 添加到已获授权的重定向 URI 中。重定向 URI 包含架构、完全限定的主机名和路径,并且必须符合重定向 URI 验证规则。例如 https://www.example.com/auth-receiver

“使用 Google 帐号登录”和“一键登录”身份验证都包含一个同意屏幕,告知用户请求访问其数据的应用、要求他们提供的数据类型以及适用的条款。

  1. 打开 Google Developer Console 中“API 和服务”部分的 OAuth 同意屏幕页面。
  2. 如果出现提示,请选择您刚刚创建的项目。
  3. 在“OAuth 同意屏幕”页面上,填写表单,然后点击“保存”按钮。

    1. 应用名称:请求用户同意的应用的名称。 该名称应准确反映您的应用,并与用户在其他位置看到的应用名称保持一致。

    2. 应用徽标:此图片显示在同意屏幕上,以帮助用户识别您的应用。该徽标显示在“使用 Google 帐号登录”同意屏幕和帐号设置中,但不会在“一键点按”对话框中显示。

    3. 支持电子邮件地址:显示在同意屏幕上(用于提供用户支持),以及由 G Suite 管理员评估用户是否有权访问您的应用。当用户点击应用名称时,系统会在“使用 Google 帐号登录”同意界面上向用户显示此电子邮件地址。

    4. Google API 的范围:借助范围,您的应用可以访问用户的私有数据。对于身份验证,默认范围(电子邮件、个人资料、openid)就足够了,您无需添加任何敏感范围。最佳做法一般是在需要访问权限时逐步请求范围,而不是提前请求。了解详情

    5. 已获授权的网域:为了保护您和您的用户,Google 仅允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情

    6. 应用首页链接:显示在“使用 Google 账号登录”同意屏幕和“一键式 GDPR 合规”免责声明信息的“继续为”按钮下方显示。必须托管在已获授权的网域上。

    7. 应用隐私权政策链接:在“使用 Google 同意登录”界面和“继续为”按钮下显示符合 GDPR 的一键式免责声明信息。必须托管在已获授权的网域上。

    8. 应用服务条款链接(可选):在“使用 Google 账号登录”权限请求页面显示;在“使用 Google 账号登录”按钮下方显示符合 GDPR 的一键式免责声明信息。必须托管在已获授权的网域上。

  4. 查看“验证状态”。如果您的应用需要验证,请点击“提交验证”按钮,提交您的应用进行验证。如需了解详情,请参阅 OAuth 验证要求

在登录期间显示 OAuth 设置

一键快捷功能

一键显示的 OAuth 用户意见征求设置

在征求用户同意时,系统会显示应用名称

使用 FedCM 一键搞定

Chrome 一键使用 FedCM 显示的 OAuth 用户意见征求设置

在 Chrome 中征得用户同意时,会显示顶级已获授权的网域

图 1. 在 Chrome 中通过“一键快捷功能”显示的 OAuth 意见征求设置。

内容安全政策

内容安全政策虽然是可选的,但我们建议您执行,以保护应用并防范跨站脚本 (XSS) 攻击。如需了解详情,请参阅 CSP 简介以及 CSP 和 XSS

您的内容安全政策可能包含一条或多条指令,例如 connect-srcframe-srcscript-srcstyle-srcdefault-src

如果您的 CSP 包含以下内容:

  • connect-src 指令,添加 https://accounts.google.com/gsi/ 以允许页面加载 Google Identity 服务服务器端端点的父网址。
  • frame-src 指令中,添加 https://accounts.google.com/gsi/ 以允许“一键快捷功能”和“使用 Google 帐号登录”按钮 iframe 的父网址。
  • script-src 指令中,添加 https://accounts.google.com/gsi/client 以允许 Google Identity 服务 JavaScript 库的网址。
  • style-src 指令,添加 https://accounts.google.com/gsi/style 以允许 Google Identity 服务样式表的网址。
  • 如果使用了 default-src 指令,则系统会在未指定前述任何指令(connect-srcframe-srcscript-srcstyle-src)时使用回退机制,添加 https://accounts.google.com/gsi/ 以允许页面加载 Google Identity 服务服务器端端点的父网址。

使用 connect-src 时,请避免列出单个 GIS 网址。这有助于在 GIS 更新时最大限度地减少失败。例如,不要添加 https://accounts.google.com/gsi/status,而应使用 GIS 父级网址 https://accounts.google.com/gsi/

以下示例响应标头允许 Google Identity 服务成功加载和执行:

Content-Security-Policy-Report-Only: script-src
https://accounts.google.com/gsi/client; frame-src
https://accounts.google.com/gsi/; connect-src https://accounts.google.com/gsi/;

跨域开启者政策

“使用 Google 账号登录”按钮和 Google 一键快捷功能可能需要更改您的 Cross-Origin-Opener-Policy (COOP),才能成功创建弹出式窗口。

启用 FedCM 后,浏览器会直接呈现弹出式窗口,无需进行任何更改。

但是,在停用 FedCM 后,应设置 COOP 标头:

  • 目的地:same-origin
  • 包括 same-origin-allow-popups

如果未能设置正确的标头,窗口之间的通信就会中断,从而导致出现空白弹出式窗口或类似 bug。