使用 FedCM API 进行 Google 登录

本指南介绍了 Google 登录平台库对 FedCM API 的采用。主题包括:时间轴和后续步骤(用于对库进行向后兼容的更新)、如何进行影响评估并验证用户登录是否继续按预期运行,以及更新 Web 应用的说明(如有需要)。此外,还介绍了管理过渡期的选项以及如何获取帮助。

库的状态

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

向后兼容的更新会将 FedCM API 添加到 Google 登录库中。 虽然大多数更改都是无缝的,但此次更新在用户提示、iframe 权限政策和内容安全政策 (CSP) 方面引入了一些差异。这些变更可能会影响您的 Web 应用,并需要您更改应用代码和网站配置。

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

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

时间表

上次更新时间:2025 年 4 月

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

  • 2023 年 3 月 弃用对 Google 登录平台库的支持。
  • 2024 年 7 月过渡期开始,Google 登录平台库添加了对 FedCM API 的支持。默认情况下,Google 会控制在此期间使用 FedCM 的用户登录请求的百分比,而 Web 应用可以使用 use_fedcm 参数明确替换此行为。
  • 2025 年 8 月:强制要求 Google 登录平台库采用 FedCM API。

后续步骤

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

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

开展影响评估

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

设置

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

在继续之前:

  • 更新到最新版本 Chrome 桌面版。Android 版 Chrome 需要 M128 或更高版本,无法使用更低版本进行测试。
  • 在 Web 应用中初始化 Google 登录平台库时,将 use_fedcm 设置为 true。通常,JavaScript 初始化如下所示:

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

    或者,您也可以使用 meta 标记在 HTML 中启用 FedCM:

    • <meta name="google-signin-use_fedcm" content="true">
  • 使 Google 登录平台库的缓存版本失效。 通常,此步骤是不必要的,因为通过在 <script src> 标记中添加 api.js、client.js 或 platform.js,最新版本的库会直接下载到浏览器(请求可以使用库的任何这些软件包名称)。

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

    1. 打开 Google API 控制台的“凭据”页面
    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 中,打开开发者工具的网络面板,然后重新加载页面。
  • 使用网域和名称列中的值找到库请求:
    • 网域为 apis.google.com,且
    • 名称为 api.js、client.js 或 platform.js。Name 的具体值取决于文档请求的库软件包。

例如,在网域列中过滤 apis.google.com,在名称列中过滤 platform.js。

检查 iframe 权限政策

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

按照找到 Google 登录库请求说明操作后,在开发者工具网络面板中选择 Google 登录库请求,然后在标头标签页的请求标头部分中找到 Sec-Fetch-Site 标头。如果标头的值为:

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

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

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

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

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

检查内容安全政策

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

按照找到 Google 登录库请求说明操作后,在开发者工具网络面板中选择 Google 登录库请求,然后在标头标签页的响应标头部分中找到 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 登录按钮

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

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

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

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

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

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

  • 监控用户的会话状态

    在此演示中,用户通过按按钮来登录和退出。 用户需要进行互动才能登录并建立新会话。

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

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

  • 请求其他权限

    在此演示中,按下按钮可用于请求其他 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。

  • 适用于服务器端应用的 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 上搜索或提问。