使用 FedCM API 进行 Google 登录

<ph type="x-smartling-placeholder">

本指南讨论了弃用第三方 Cookie 对 Google 登录平台库。主题包括时间轴和 有关库向后兼容更新的后续步骤,以及如何 执行影响评估并验证用户登录是否继续 按预期运行,以及更新 Web 应用的说明(如果需要)。 管理过渡期以及获取帮助的选项 也包括在内

库的状态

所有新的 Web 应用都将无法使用已弃用的 Google 登录平台 而使用该库的应用可以继续使用,直至另行通知。答 该库的最终停用日期(停用)尚未确定。 如需了解详情,请参阅弃用支持并停用

Chrome 的 Privacy Sandbox 阻止第三方 Cookie 会影响 Web 应用 使用 Google 登录平台库的应用。要保留现有行为 而无需使用第三方 Cookie, 将 FedCM API 添加到了此库中。虽然大多数更改都是无缝的,但 更新引入了用户意见征求提示、iframe 方面的差异, permissions-policy内容安全政策 (CSP)。这些更改 可能会影响您的 Web 应用,并需要对应用代码和网站进行更改 配置。

在过渡期间,由一个配置选项控制 用户登录期间会使用 FedCM API。

时间轴

上次更新时间:2024 年 7 月

下面列出了影响用户登录行为的日期和变化:

  • 2023 年 3 月 停止支持 Google 登录平台 库。
  • 2024 年 1 月:Chrome 会阻止 1% 的第三方 Cookie(即 Google 登录) 平台库暂时获得第三方 Cookie 豁免 在弃用试用期间阻止运行。
  • 2024 年 7 月过渡期开始,Google 登录平台库 添加了对 FedCM API 的支持。默认情况下,Google 会控制 在此期间使用 FedCM 发出了登录请求。Web 应用可以 您可以使用 use_fedcm 参数明确替换此行为。
  • Google 强制采用(日期待定)FedCM API 登录平台库;之后 use_fedcm 参数将被忽略; 并且所有用户登录请求均使用 FedCM。

迁移到 FedCM API 后,Google 登录平台库将不再用于 受第三方 Cookie 屏蔽影响的广告。关于第三方 Cookie 的更新 请参阅 Chrome 的 Privacy Sandbox 时间表

后续步骤

您可以选择采用以下三种方法:

  1. 开展影响评估,并根据需要更新您的 Web 应用。 此方法可评估需要更改 Web 应用的功能是否 使用中。有关说明,请参阅本指南的下一部分。
  2. 移至 Google Identity 服务 (GIS) 库。迁移到 强烈建议您使用受支持的登录库为此,请按照 这些说明
  3. 什么也不做。您的 Web 应用将在 Google 登录库改用 FedCM API 进行用户登录。这是 最省时,但也存在用户无法登录 您的 Web 应用。

开展影响评估

请按照以下说明确定您的 Web 应用是否可以无缝更新 (例如通过向后兼容的更新), 当 Google 登录平台库完全覆盖时,用户无法登录 采用 FedCM API。

设置

浏览器 API 和最新版本的 Google 登录平台库 。

在继续之前,请执行以下操作:

  • 将桌面版 Chrome 更新到最新版本。Android 版 Chrome 需要 M128 或更高版本,无法使用早期版本进行测试。
  • 打开 chrome://flags 并将以下功能设置为这些值:

    • #fedcm-authz(如果您的网站使用内容安全政策)已启用 阻止https://accounts.google.com/gsi/ottoken
    • #tracking-protection-3pcd 已启用
    • #third-party-cookie-deprecation-trial 已停用
    • #tpcd-metadata-grants 已停用
    • #tpcd-heuristics-grants 已停用

    然后重新启动 Chrome。

  • 初始化 Google 登录平台时,将 use_fedcm 设置为 true 库。通常,初始化应如下所示:

    • gapi.client.init({use_fedcm: true}),或者
    • gapi.auth2.init({use_fedcm: true}),或者
    • gapi.auth2.authorize({use_fedcm: true})
  • 使 Google 登录平台库的缓存版本失效。 通常不需要执行此步骤,因为已安装了该库的最新版本 (通过添加 api.jsclient.js<script src> 标记中的 platform.js(该请求可以使用以下任何一项: 库的软件包名称)。

  • 确认您的 OAuth 客户端 ID 的 OAuth 设置:

    1. 打开 Google API Console的“凭据”页面
    2. 验证您网站的 URI 是否包含在 已获授权的 JavaScript 来源。URI 包含架构和 全限定主机名。例如 https://www.example.com

    3. (可选)可以使用到端点的重定向返回凭据 而不是通过 JavaScript 回调来托管。如果遇到这种情况 验证您的重定向 URI 是否包含在已获授权的重定向 URI 中。 重定向 URI 包括架构、完全限定主机名和路径 并且必须遵循重定向 URI 验证规则。例如 https://www.example.com/auth-receiver

测试

按照“设置”中的说明操作后:

找到 Google 登录库请求

检查 permissions-policy内容安全政策更改是否 检查 Google 登录平台库的请求。 为此,请使用库的名称和来源找到相应请求:

  • 在 Chrome 中,打开开发者工具 Network 面板并重新加载页面。
  • 使用 DomainName 列中的值找到库 请求: <ph type="x-smartling-placeholder">
      </ph>
    • 域名为 apis.google.com
    • 名称是 api.jsclient.jsplatform.js。使用 Name 的值取决于文档请求的库包。

例如,在网域列中按 apis.google.com 进行过滤,并将 platform.js(在 Name 列中)。

检查 iframe 权限政策

您的网站可能在跨源应用中使用 Google 登录平台库 iframe。如果是这样,则需要进行更新。

完成查找 Google 登录库请求后 说明,请在开发者工具中选择 Google 登录库请求 网络面板,然后在以下位置找到 Sec-Fetch-Site 标头: Headers 标签页中的 Request Headers 部分。如果标头中的值 :

  • same-sitesame-origin,则跨源政策不适用,并且 更改。
  • 如果使用了 iframe,则可能需要更改 cross-origin

要确认是否存在 iframe,请执行以下操作:

  • 在 Chrome 开发者工具中选择 Elements 面板,然后
  • 使用 Ctrl-F 在文档中查找 iframe。

如果找到了 iframe,请检查文档以检查对 gapi.auth2 的调用情况 函数script src 指令来加载 Google 登录库 。如果遇到这种情况,请按以下指示操作:

对文档中的每个 iframe 重复此过程。iframe 可以嵌套 请务必将 allow 指令添加到所有周围的父 iframe 中。

查看内容安全政策

如果您的网站使用了内容安全政策,您可能需要将 CSP 更新为 允许使用 Google 登录库。

完成查找 Google 登录库请求后 说明,请在开发者工具中选择 Google 登录库请求 网络面板,然后在以下位置找到 Content-Security-Policy 标头: Headers 标签页的 Response Headers 部分。

如果未找到该标头,则无需进行任何更改。否则,请查看 这些 CSP 指令在 CSP 标头中定义,并通过以下方式更新:

  • 正在添加https://apis.google.com/js/https://accounts.google.com/gsi/、 并将https://acounts.google.com/o/fedcm/分配给任何connect-srcdefault-srcframe-src 指令。

  • https://apis.google.com/js/bundle-name.js 添加到 script-src 指令。将 bundle-name.js 替换为 api.jsclient.jsplatform.js

检查用户提示更改

用户提示行为存在一些差异,FedCM 添加了一个模态对话框 并更新用户激活要求。

FedCM 模态对话框的图片

检查网站的布局,确认基础内容可以 安全叠加,并被浏览器的模态对话框暂时遮挡。如果 您可能需要调整某些元素的布局或位置 。

用户激活

FedCM 包含更新后的用户激活要求。按某个按钮或 例如,允许第三方来源点击链接的用户手势 发出网络请求或存储数据使用 FedCM 时,浏览器会提示 用户意见征求:

  • 当用户首次使用新的浏览器实例登录 Web 应用时触发,或者
  • 调用 GoogleAuth.signIn

现在,如果用户以前登录过您的网站,您可以获取 用户在初始化 Google Sign-In 库时的登录信息 使用 gapi.auth2.init,而无需进行进一步的用户互动。

由于第三方 Cookie 已弃用,除非 用户首次完成 FedCM 登录流程一次。

选择启用 FedCM 并在下次遇到相同的情况时致电 GoogleAuth.signIn, 用户访问您的网站,gapi.auth2.init 可以获取用户的登录信息 信息。

常见使用场景

Google 登录库的开发者文档包含指南和代码 常见使用场景示例。本部分将讨论 FedCM 如何影响其 行为

  • 将 Google 登录功能集成到您的 Web 应用中

    在此demo中,由一个 <div> 元素和一个类渲染该按钮,以及 对于已登录的用户,页面 onload 事件会返回用户 凭据。需要用户互动才能登录和创建新的 会话。

    库初始化由 g-signin2 类完成,该类会调用 gapi.loadgapi.auth2.init

    用户手势(<div> 元素 onclick 事件)调用 auth2.signIn 或者在退出时auth2.signOut

  • 构建自定义 Google 登录按钮

    演示 1 中,自定义属性用于控制 登录按钮;对于已登录的用户,则为页面 onload 事件 返回用户凭据。需要用户互动才能登录和 建立新会话。

    库初始化通过 onload 事件完成,对于 platform.js 库,并且按钮由 gapi.signin2.render 显示。

    用户手势按登录按钮,会调用 auth2.signIn

    演示 2 中,<div> 元素、CSS 样式和自定义图形 用于控制登录按钮的外观。用户互动 登录和建立新会话所需的资源。

    库初始化在文档加载时使用 start 函数完成 它会调用 gapi.loadgapi.auth2.initgapi.auth2.attachClickHandler

    用户手势(<div> 元素 onclick 事件)调用 auth2.signIn 在登录期间使用auth2.attachClickHandler或在登录状态下使用auth2.signOut 退出。

  • 监控用户的会话状态

    在此demo中,按下按钮来供用户登录和退出账号。 需要用户互动才能登录和建立新会话。

    库初始化是通过直接调用 gapi.load 完成的, gapi.auth2.init,之后 gapi.auth2.attachClickHandler() platform.js 是使用 script src 加载的。

    用户手势(<div> 元素 onclick 事件)调用 auth2.signIn 在登录期间使用auth2.attachClickHandler或在登录状态下使用auth2.signOut 退出。

  • 请求其他权限

    在此demo中,按下按钮来请求额外的 OAuth 2.0 获取新的访问令牌,而对于已经登录的用户, 页面 onload 事件会返回用户凭据。用户互动为必填项 登录并建立新会话。

    库初始化通过 onload 事件完成, platform.js 库(通过调用 gapi.signin2.render)。

    用户手势点击 <button> 元素会触发对 使用 googleUser.grantauth2.signOut 的额外 OAuth 2.0 范围 退出。

  • 使用监听器集成 Google 登录

    在此demo中,对于已登录的用户,页面 onload 事件 返回用户凭据。需要用户互动才能登录和 建立新会话。

    库初始化在文档加载时使用 start 函数完成 它会调用 gapi.loadgapi.auth2.initgapi.auth2.attachClickHandler。下一条:auth2.isSignedIn.listen auth2.currentUser.listen 用于设置对以下内容的更改通知: 会话状态最后,调用 auth2.SignIn 以返回 已登录的用户

    用户手势(<div> 元素 onclick 事件)调用 auth2.signIn 在登录期间使用auth2.attachClickHandler或在登录状态下使用auth2.signOut 退出。

  • 适用于服务器端应用的 Google 登录功能

    在本demo中,用户手势用于请求 OAuth 2.0 身份验证代码 以及 JS 回调进行 AJAX 调用以将响应发送到后端 服务器进行验证。

    使用 platform.jsonload 事件完成库初始化 库,该库使用 start 函数来调用 gapi.loadgapi.auth2.init

    用户手势点击 <button> 元素会触发对 通过调用 auth2.grantOfflineAccess 获得授权代码。

  • 跨平台单点登录

    FedCM 要求针对每个浏览器实例征得用户同意,即使 Android 用户也是如此 请登录,则需获得一次性同意。

管理过渡期

在过渡期间,一定比例的用户登录可使用 FedCM、 确切百分比可能会有所不同,并且可能会随时间而变化。默认情况下,Google 控件 使用 FedCM 的登录请求数量,但您可以选择启用或停用 使用 FedCM。过渡期结束时 FedCM 成为强制性要求,并且适用于所有登录请求。

如果选择选择加入,用户将先完成 FedCM 登录流程,同时选择 提示用户完成现有的登录流程。这种行为 使用 use_fedcm 参数控制。

选择启用

因此,您不妨控制一下是允许所有或部分登录您 是否使用 FedCM API。为此,请在初始化时将 use_fedcm 设置为 true 平台库在这种情况下,用户登录请求使用 FedCM API。

选择停用

在过渡期间,有一定比例的用户尝试登录您的网站 将使用 FedCM API。如果您需要更多时间来修改 应用,您可以暂时选择停用 FedCM API。为此,请将 初始化平台库时,将 use_fedcm 设置为 false。用户登录 请求将不会使用 FedCM API。

强制采用后,系统会忽略所有 use_fedcm 设置, Google 登录平台库。

获取帮助

使用 google-signin 标签在 StackOverflow 中搜索或提问。