使用 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 或更高版本，无法使用较低版本进行测试。
• 在 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。

测试

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

• 关闭所有现有的 Chrome 无痕式窗口，然后打开一个新的无痕式窗口。这样做会清除所有缓存内容或 Cookie。
• 加载用户登录页面，然后尝试登录。

• 请按照本指南中以下部分中的说明来识别和解决已知问题：

  • 找到 Google 登录库请求
  • 查看 iframe 权限政策
  • 查看内容安全政策
  • 检查用户提示是否发生了变化

• 在控制台中查找与 Google 登录库相关的任何错误或警告。

• 重复此过程，直到不再出现错误并能成功登录。您可以通过确认 BasicProfile.getEmail() 返回您的电子邮件地址，以及 GoogleUser.isSignedIn() 为 True 来验证登录是否成功。

找到 Google 登录库请求

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

• 在 Chrome 中，打开开发者工具的网络面板，然后重新加载网页。
• 使用网域和名称列中的值查找相应库请求：
  • 域名为 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 DevTools 中选择元素面板，然后
• 使用 Ctrl-F 在文档中查找 iframe。

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

• 将 allow="identity-credentials-get" 权限政策添加到父级 iframe。

对文档中的每个 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 时，浏览器会在以下情况下提示用户同意：

• 用户首次使用新的浏览器实例登录 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 的 start 函数完成的。接下来，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 上搜索或提问。