使用 FedCM API 进行 Google 登录

本指南介绍了 Google 登录平台库如何采用 FedCM API。主题包括库向后兼容更新的时间表和后续步骤、如何进行影响评估并验证用户登录是否继续按预期运行，以及在必要时更新 Web 应用的说明。管理过渡期的选项以及如何获取帮助也将在其中介绍。

库的状态

任何新的 Web 应用都无法使用已废弃的 Google 登录平台库，但在另行通知之前，使用该库的应用可以继续使用。该库的最终弃用日期（关停日期）尚未确定。如需了解详情，请参阅支持的弃用和弃用。

此向后兼容的更新会向 Google 登录库添加 FedCM API。虽然大多数变更都很顺畅，但此更新会导致用户提示、iframe permissions-policy 和内容安全政策 (CSP) 出现差异。这些更改可能会影响您的 Web 应用，并且需要更改应用代码和网站配置。

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

过渡期结束后，所有使用 Google 登录库的 Web 应用都必须使用 FedCM API。

时间轴

上次更新时间：2024 年 9 月

以下是影响用户登录行为的日期和变更：

  • 2023 年 3 月 弃用对 Google 登录平台库的支持。
  • 2024 年 7 月过渡期开始，并添加了对 FedCM API 的 Google 登录平台库支持。在此期间，默认情况下，Google 会使用 FedCM 控制用户登录请求的百分比。网络应用可以使用 use_fedcm 参数显式替换此行为。
  • 2025 年 3 月 Google 登录平台库必须采用 FedCM API，之后系统会忽略 use_fedcm 参数，并且所有用户登录请求都会使用 FedCM。

后续步骤

您可以选择以下三种方式：

  1. 开展影响评估，并根据需要更新您的 Web 应用。此方法可评估是否正在使用需要更改 Web 应用的功能。本指南的下一部分提供了相关说明。
  2. 迁移到 Google Identity 服务 (GIS) 库。强烈建议改用最新的受支持的登录库。为此，请按照这些说明操作。
  3. 什么也不做。当 Google 登录库改用 FedCM API 进行用户登录时，您的 Web 应用将自动更新。这种方式的工作量最少，但存在用户无法登录您的 Web 应用的风险。

开展影响评估

请按照以下说明确定您的 Web 应用能否通过向后兼容的更新进行无缝更新，或者是否需要进行更改，以免在 Google 登录平台库全面采用 FedCM API 时用户无法登录。

设置

如需在用户登录期间使用 FedCM，必须使用浏览器 API 和最新版本的 Google 登录平台库。

在继续之前：

  • 请更新到最新版 Chrome 桌面版。Android 版 Chrome 需要 M128 或更高版本，无法使用较低版本进行测试。

  • 打开 chrome://flags 并将以下功能设置为这些值：

    • #fedcm-authz 已启用
    • #tracking-protection-3pcd 已启用
    • #third-party-cookie-deprecation-trial 已停用
    • #tpcd-metadata-grants 已停用
    • #tpcd-heuristics-grants 已停用

    然后重新启动 Chrome。

  • 在 Web 应用中初始化 Google 登录平台库时，将 use_fedcm 设置为 true。通常，初始化如下所示：

    • gapi.client.init({use_fedcm: true})，或者
    • gapi.auth2.init({use_fedcm: true})，或者
    • gapi.auth2.authorize({use_fedcm: true})。

  • 使 Google 登录平台库的缓存版本失效。通常，此步骤是不需要的，因为通过在 <script src> 标记中添加 api.js、client.js 或 platform.js，系统会将最新版本的库直接下载到浏览器（请求可以使用库的任何这些软件包名称）。

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

    1. 打开 Google API Console的“凭据”页面

    2. 验证您网站的 URI 是否包含在已获授权的 JavaScript 来源中。URI 仅包含架构和完全限定的主机名。例如 https://www.example.com。

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

测试

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

找到 Google 登录库请求

通过检查 Google 登录平台库的请求，检查是否需要 permissions-policy 和内容安全政策更改。为此，请使用库的名称和来源查找请求：

  • 在 Chrome 中，打开 DevTools 的 Network 面板，然后重新加载页面。
  • 使用网域和名称列中的值查找相应库请求：
    • 网域为 apis.google.com，并且
    • 名称为 api.js、client.js 或 platform.js。Name 的具体值取决于文档请求的库包。

例如，按网域列中的 apis.google.com 和名称列中的 platform.js 进行过滤。

检查 iframe 权限政策

您的网站可能会在跨源 iframe 中使用 Google 登录平台库。如果是，则需要更新。

按照查找 Google 登录库请求中的说明操作后，在 DevTools 的 Network 面板中选择 Google 登录库请求，然后在 Headers 标签页的 Request Headers 部分中找到 Sec-Fetch-Site 标头。如果标头的值为：

  • same-site 或 same-origin，则跨源政策不适用，也无需进行任何更改。
  • 如果使用的是 iframe，则可能需要进行 cross-origin 更改。

如需确认是否存在 iframe，请执行以下操作：

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

如果找到 iframe，请检查文档，看看是否有对 gapi.auth2 函数或在 iframe 中加载 Google 登录库的 script src 指令的调用。如果遇到这种情况，请按以下指示操作：

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

查看内容安全政策

如果您的网站使用内容安全政策 (CSP)，您可能需要更新 CSP 才能使用 Google 登录库。

按照查找 Google 登录库请求中的说明操作后，在 DevTools 的 Network 面板中选择 Google 登录库请求，然后在 Headers 标签页的 Response Headers 部分找到 Content-Security-Policy 标头。

如果找不到该标头，则无需进行任何更改。否则，请检查是否在 CSP 标头中定义了这些 CSP 指令，并通过以下方式更新它们：

  • 向任何 connect-src、default-src 或 frame-src 指令添加 https://apis.google.com/js/、https://accounts.google.com/gsi/ 和 https://acounts.google.com/o/fedcm/。

  • 将 https://apis.google.com/js/bundle-name.js 添加到 script-src 指令。根据文档请求的库软件包，将 bundle-name.js 替换为 api.js、client.js 或 platform.js。

检查用户提示是否有更改

用户提示行为有一些差异，FedCM 添加了浏览器显示的模态对话框，并更新了用户激活要求。

FedCM 模态对话框的图片

检查网站的布局，确认底层内容能否被浏览器的模态对话框安全地叠加以及暂时遮挡。如果不是，您可能需要调整网站上某些元素的布局或位置。

用户激活

FedCM 包含更新后的用户激活要求。按按钮或点击链接是允许第三方来源发出网络请求或存储数据的用户手势示例。使用 FedCM 时，浏览器会在以下情况下提示用户同意：

  • 用户首次使用新的浏览器实例登录 Web 应用，或者
  • 调用 GoogleAuth.signIn。

目前，如果用户之前已登录您的网站，您可以在使用 gapi.auth2.init 初始化 Google 登录库时获取用户的登录信息，而无需进一步的用户互动。除非用户先前至少完成了一次 FedCM 登录流程，否则无法再这样做。

通过选择启用 FedCM 并调用 GoogleAuth.signIn，当同一用户下次访问您的网站时，gapi.auth2.init 可以在初始化期间获取用户的登录信息，而无需用户互动。

常见使用场景

Google 登录库的开发者文档包含适用于常见用例的指南和代码示例。本部分介绍了 FedCM 对其行为的影响。

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

    在此演示中，<div> 元素和一个类会呈现按钮，对于已登录的用户，网页 onload 事件会返回用户凭据。需要用户互动才能登录并建立新会话。

    库初始化由 g-signin2 类完成，该类会调用 gapi.load 和 gapi.auth2.init。

    用户手势（<div> 元素 onclick 事件）会在登录期间调用 auth2.signIn，在退出登录时调用 auth2.signOut。

  • 构建自定义 Google 登录按钮

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

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

    用户按下登录按钮的手势会调用 auth2.signIn。

    在演示二中，<div> 元素、CSS 样式和自定义图形用于控制登录按钮的外观。需要用户互动才能登录并建立新会话。

    库初始化在文档加载时使用启动函数（调用 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler）完成。

    用户手势（<div> 元素 onclick 事件）会在登录期间使用 auth2.attachClickHandler 调用 auth2.signIn，或在退出登录时使用 auth2.signOut 调用 auth2.signIn。

  • 监控用户的会话状态

    在此演示中，按下按钮用于用户登录和退出。 需要用户互动才能登录并建立新会话。

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

    用户手势（<div> 元素 onclick 事件）会在登录期间使用 auth2.attachClickHandler 调用 auth2.signIn，或在退出登录时使用 auth2.signOut 调用 auth2.signIn。

  • 请求其他权限

    在此演示中，按下按钮用于请求其他 OAuth 2.0 范围，获取新的访问令牌；对于已登录的用户，页面 onload 事件会返回用户凭据。需要用户互动才能登录和建立新会话。

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

    用户点击 <button> 元素时，系统会在用户退出账号时触发使用 googleUser.grant 或 auth2.signOut 请求其他 OAuth 2.0 权限。

  • 使用监听器集成 Google 登录

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

    库初始化是在文档加载时使用调用 gapi.load、gapi.auth2.init 和 gapi.auth2.attachClickHandler 的开始函数完成的。接下来，auth2.isSignedIn.listen 和 auth2.currentUser.listen 用于设置有关会话状态更改的通知。最后，系统会调用 auth2.SignIn 以返回已登录用户的凭据。

    用户手势（<div> 元素 onclick 事件）会在登录期间使用 auth2.attachClickHandler 调用 auth2.signIn，或在退出登录时使用 auth2.signOut 调用 auth2.signIn。

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

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

    库初始化是使用 platform.js 库的 onload 事件完成的，该事件使用 start 函数调用 gapi.load 和 gapi.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。

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

获取帮助

使用 google-signin 标记在 StackOverflow 上搜索或提问。