从 Google 登录功能迁移

本指南可帮助您了解将 JavaScript 库从旧版 Google 登录平台库成功迁移到新版 Google Identity 服务库以进行身份验证所需的更改和步骤。

如果您的客户端使用适用于 JavaScript 的 Google API 客户端库或其他早期库进行授权，请参阅迁移到 Google Identity 服务了解详情。

身份验证与授权

身份验证用于确定用户的身份，通常称为“用户注册”或“登录”。授权是授予或拒绝对数据或资源的访问权限的过程。例如，您的应用会请求用户同意访问用户的 Google 云端硬盘。

与之前的 Google 登录平台库一样，新的 Google Identity 服务库可同时支持身份验证和授权流程。

不过，新版库将这两个流程分离，以降低开发者将 Google 帐号与应用集成的复杂性。

如果您的用例仅涉及身份验证，请继续阅读本页面。

如果您的用例包含授权，请参阅用户授权的工作原理和迁移到 Google Identity 服务，以确保您的应用使用的是经过改进的新 API。

具体变化

新的 Google Identity 服务库为用户提供了多项可用性改进。其特点包括：

  • 新的顺畅的一键快捷登录和自动登录流程，包含更少的具体步骤，
  • 采用用户个性化设置的全新登录按钮
  • 在整个网络上采用一致的品牌信息和登录行为 有助于增进用户的了解和信任
  • 用户可以快速访问您网站上的内容；用户可以从您网站上的任意位置直接注册和登录，而无需先访问登录或帐号页面。

对开发者而言，我们的重点是降低复杂性、提高安全性并尽快完成集成。其中部分改进包括：

  • 该选项让用户可以只使用 HTML 代码向网站的静态内容中添加登录机制
  • 登录身份验证与授权分离，并且用户数据共享不再是复杂的 OAuth 2.0 集成，让用户登录您的网站时，
  • 弹出式广告和重定向模式仍继续受支持，但 Google 的 OAuth 2.0 基础架构现在会重定向到后端服务器的登录端点
  • 将较旧版本的 Google Identity 和 Google API JavaScript 库的功能整合到一个新库中
  • 对于登录响应，您现在可以决定是否使用 Promise，并且为简单起见，已移除通过 getter 样式函数进行的间接调用。

登录迁移示例

如果您要从现有的 Google 登录按钮进行迁移，并且只想让用户登录您的网站，那么最直接的更改就是更新到新的个性化按钮。这可以通过交换 JavaScript 库并更新代码库以使用新的登录对象来实现。

库和配置

用户身份验证和授权不再需要早期的 Google 登录平台库 apis.google.com/js/platform.js 和适用于 JavaScript 的 Google API 客户端库 gapi.client。它们已被单个新的 Google Identity 服务 JavaScript 库取代：accounts.google.com/gsi/client。

前三个 JavaScript 模块（api、client 和 platform 用于登录）都从 apis.google.com 加载。为了帮助您识别网站中可能包含旧版库的位置，通常可以执行以下操作：

  • 默认登录按钮会加载 apis.google.com/js/platform.js，
  • 自定义按钮图形加载了 apis.google.com/js/api:client.js；
  • 直接使用 gapi.client 会加载 apis.google.com/js/api.js。

在大多数情况下，您可以继续使用现有的 Web 应用客户端 ID 凭据。在迁移过程中，建议您查看我们的 OAuth 2.0 政策并使用 Google API 控制台进行确认，如有必要，请更新以下客户端设置：

  • 您的测试版应用和正式版应用使用不同的项目，并且具有自己的客户端 ID
  • “OAuth 2.0 Client ID Type”为“Web application”；
  • HTTPS 用于已获授权的 JavaScript 来源和重定向 URI。

找出受影响的代码并进行测试

调试 Cookie 可帮助您找到受影响的代码并测试弃用后的行为。

在大型或复杂的应用中，可能很难找到所有受 gapi.auth2 模块废弃影响的代码。如需将即将弃用的功能的现有使用情况记录到控制台，请将 G_AUTH2_MIGRATION Cookie 的值设置为 informational。（可选）添加一个英文冒号，后跟一个键值对，以便将日志也记录到会话存储空间中。登录并收到凭据后，请审核或将收集的日志发送到后端以供日后分析。例如，informational:showauth2use 会将来源和网址保存到名为 showauth2use 的会话存储密钥中。

如需验证 gapi.auth2 模块不再加载时的应用行为，请将 G_AUTH2_MIGRATION Cookie 的值设置为 enforced。这样一来，您就可以在强制执行日期之前测试弃用后的行为。

可能的 G_AUTH2_MIGRATION Cookie 值：

  • enforced 请勿加载 gapi.auth2 模块。
  • informational 将已弃用功能的使用情况记录到 JS 控制台中。设置可选键名称时，还应记录到会话存储空间：informational:key-name。

为了最大限度地减少对用户的影响，建议您在开发和测试期间先在本地设置此 Cookie，然后再在生产环境中使用。

HTML 和 JavaScript

在这种仅进行身份验证的登录场景中，系统会显示示例代码以及现有 Google 登录按钮的呈现效果。选择“弹出式”或“重定向”模式，以查看通过 JavaScript 回调或安全重定向到后端服务器登录端点的方式处理身份验证响应的方式有何不同。

方法比较简单，

呈现 Google 登录按钮，并使用回调来处理直接从用户浏览器进行的登录。

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

重定向模式

呈现 Google 登录按钮，并以从用户浏览器到后端服务器登录端点的 AJAX 调用结束。

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

已渲染

新的视觉属性简化了之前创建自定义按钮的方法，消除了对 gapi.signin2.render() 的调用，并且无需在您的网站上托管和维护图片和视觉资源。

Google 登录功能

Google 登录

用户登录状态更新按钮文字。

全新方式

如需在仅进行身份验证的登录场景中使用新库，请选择“弹出式窗口”或“重定向”模式，并使用代码示例替换登录页面上的现有实现。

使用回调处理直接从用户浏览器进行的登录。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

重定向模式

Google 会按照 data-login_url 属性所指定的方式调用您的登录端点。以前，您负责 POST 操作和参数名称。新库会将 ID 令牌发布到您的端点 credential 参数中。最后，在后端服务器上验证 ID 令牌。

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

已渲染

您可以使用视觉属性来自定义“使用 Google 帐号登录”按钮的大小、形状和颜色。显示一键式弹出式窗口以及个性化按钮，以提高登录率。

“使用 Google 帐号登录”按钮 一键式弹出式窗口

用户登录状态不会将按钮文本从“登录”更新为“已登录”。表示同意后或回访时，此个性化按钮会包含用户的姓名、电子邮件地址和个人资料照片。

在此仅身份验证的示例中，新的 accounts.google.com/gsi/client 库、g_id_signin 类和 g_id_onload 对象取代了之前的 apis.google.com/js/platform.js 库和 g-signin2 对象。

除了呈现新的个性化按钮之外，示例代码还显示了新的一键式弹出式窗口。无论您在何处显示个性化按钮，我们都强烈建议您也显示一键式弹出式窗口，以最大限度地减少用户在注册和登录期间遇到的障碍。

虽然由于登录阻力增加，但不建议这样做，但新的个性化按钮可以单独显示，而不会同时显示“一键快捷”对话框。为此，请将 data-auto_prompt 属性设置为 false。

HTML 和 JavaScript API

前面的示例展示了如何使用新的 HTML API 向网站添加登录功能。或者，您也可以使用功能等效的 JavaScript API，或在整个网站上混合搭配 HTML 和 JavaScript API 使用。

如需以交互方式查看按钮自定义选项（例如颜色、尺寸、形状、文本和主题等属性），请查看我们的代码生成器。可用于快速比较不同选项，并生成 HTML 代码段以供在您的网站上使用。

使用一键快捷功能从任意页面登录

一键快捷功能可让用户轻松顺畅地注册网站。 它可让您的用户直接从网站上的任何页面登录，让用户无需访问专用登录页面。换句话说，这样可以让用户灵活地从登录页面以外的页面注册和登录，从而减少注册和登录的麻烦。

如需支持从任何页面登录，我们建议您将 g_id_onload 添加到整个网站的共享页眉、页脚或其他对象中。

我们还建议添加 g_id_signin，它仅在您的登录或用户帐号管理页面上显示个性化登录按钮。通过将该按钮与其他联合身份提供方按钮以及用户名和密码输入字段一起显示，为用户提供注册或登录选项。

令牌响应

用户登录不再要求您了解或使用 OAuth 2.0 授权代码、访问令牌或刷新令牌。而 JSON Web 令牌 (JWT) ID 令牌将用于共享登录状态和用户个人资料。进一步简化，您不再需要使用“getter”样式的访问器方法来处理用户个人资料数据。

系统会通过以下任一方式返回由 Google 签名的 JWT ID 安全令牌凭据：

  • 在弹出模式下，响应用户基于浏览器的 JavaScript 回调处理程序的权限；或者
  • 您的后端服务器。ux_moderedirect

在这两种情况下，请通过移除以下内容来更新现有的回调处理程序：

  • 对 googleUser.getBasicProfile() 的调用，
  • 对 BasicProfile 的引用，以及对 getId()、getName()、getGivenName()、getFamilyName()、getImageUrl()、getEmail() 方法的相关调用，以及
  • 使用了 AuthResponse 对象。

请改为在新的 JWT CredentialResponse 对象中使用对 credential 子字段的直接引用，以便处理用户个人资料数据。

此外，请务必防止跨站请求伪造 (CSRF) 并在后端服务器上验证 Google ID 令牌（仅限重定向模式）。

为了更好地了解用户如何与您的网站互动，可以使用 CredentialResponse 中的 select_by 字段来确定用户意见征求结果和所使用的具体登录流程。

当用户首次登录您的网站时，Google 会提示用户同意与您的应用共享其帐号资料。只有在征得用户同意后，系统才会以 ID 令牌凭据载荷与您的应用共享用户个人资料。撤消对此配置文件的访问权限相当于在之前的登录库中撤消访问令牌。

用户可以访问 https://myaccount.google.com/permissions，撤消权限并解除您的应用与其 Google 帐号之间的关联。 或者，它们可以通过触发您实现的 API 调用直接断开与应用的连接；之前的 disconnect 方法已替换为较新的 revoke 方法。

当用户在您的平台上删除其帐号时，最佳实践是使用 revoke 解除您的应用与其 Google 帐号的关联。

以前，auth2.signOut() 可用于帮助管理用户在您的应用中退出登录的事宜。您应取消对 auth2.signOut() 的任何使用，而您的应用应直接管理每位用户的会话状态和登录状态。

会话状态和监听器

新库不会保持 Web 应用的登录状态或会话状态。

Google 帐号的登录状态与应用的会话状态和登录状态是截然不同的概念。

用户对其 Google 帐号和您的应用的登录状态是相互独立的，除非您知道用户已成功通过身份验证并登录了其 Google 帐号，否则登录时除外。

如果您的网站支持“使用 Google 帐号登录”“一键登录”或“自动登录”功能，用户必须先登录其 Google 帐号，以便：

  • 同意在首次注册或登录您的网站时共享其用户个人资料
  • 然后再设置一次，以便以后访问 网站时再登录。

在在您的网站上保持活跃的已登录会话期间，用户可能会保持已登录、退出登录或切换到其他 Google 帐号。

您现在负责直接管理 Web 应用用户的登录状态。以前，Google 登录功能有助于监控用户的会话状态。

移除对 auth2.attachClickHandler() 及其已注册的回调处理程序的任何引用。

以前，监听器用于共享用户 Google 帐号的登录状态变化。监听器已不再受支持。

移除对 listen()、auth2.currentUser 和 auth2.isSignedIn 的任何引用。

饼干

“使用 Google 帐号登录”功能对 Cookie 的使用会受到限制，并遵循对这些 Cookie 的说明。如需详细了解 Google 使用的其他类型的 Cookie，请参阅 Google 如何使用 Cookie。

系统不再使用较早的 Google 登录平台库设置的 G_ENABLED_IDPS Cookie。

新的 Google Identity 服务库可能会根据您的配置选项，选择性设置以下跨网域 Cookie：

  • g_state 会存储用户退出状态，在使用一键式弹出式窗口或自动登录时进行设置。

  • g_csrf_token 是用于防止 CSRF 攻击的双重提交 Cookie，在登录端点被调用时进行设置。登录 URI 的值可明确设置，也可默认为当前网页的 URI。在以下情况下，系统可能会调用您的登录端点：

    • 使用 data-ux_mode=redirect 或者在设置了 data-login_uri 的情况下使用 HTML API，或者

    • 将 JavaScript API 与 ux_mode=redirect 搭配使用，并且其中不使用 google.accounts.id.prompt() 显示一键快捷功能或自动登录功能。

如果您拥有管理 Cookie 的服务，请务必在迁移完成后添加两个新的 Cookie 并移除之前的 Cookie。

如果您管理多个网域或子网域，请参阅跨子网域显示一键快捷功能，了解有关如何使用 g_state Cookie 的进一步说明。

适用于用户登录的对象迁移参考文档

旧优惠 新观看者 备注
JavaScript 库
apis.google.com/js/platform.js accounts.google.com/gsi/client 用新旧替换。
apis.google.com/js/api.js accounts.google.com/gsi/client 用新旧替换。
GoogleAuth 对象及相关方法：
GoogleAuth.attachmentClickHandler() IdConfiguration.callback，适用于 JS 和 HTML data-callback 用新旧替换。
GoogleAuth.currentUser.get() 凭据响应 请改用 CredentialResponse，不再需要。
GoogleAuth.currentUser.listen() 移除。无法获取用户在 Google 上的当前登录状态。 用户必须登录 Google 才能表示同意和完成登录。 CredentialResponse 中的 select_by 字段可用于确定用户同意情况的结果以及所用的登录方法。
GoogleAuth.disconnect() google.accounts.id.revoke 用新旧替换。用户还可能会通过 https://myaccount.google.com/permissions 进行撤消
GoogleAuth.grantOffAccess() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleAuth.isSignedIn.get() 移除。无法获取用户在 Google 上的当前登录状态。 用户必须登录 Google 才能表示同意和完成登录。
GoogleAuth.isSignedIn.listen() 移除。无法获取用户在 Google 上的当前登录状态。 用户必须登录 Google 才能表示同意和完成登录。
GoogleAuth.signIn() 移除。加载 g_id_signin 元素的 HTML DOM 或对 google.accounts.id.renderButton 的 JS 调用会触发用户登录 Google 帐号。
GoogleAuth.signOut() 移除。您的应用的用户登录状态和 Google 帐号是相互独立的。不由 Google 管理您的应用的会话状态。
GoogleAuth.then() 移除。GoogleAuth 已弃用。
GoogleUser 对象及相关方法：
GoogleUser.disconnect() google.accounts.id.revoke 用新旧替换。用户还可能会通过 https://myaccount.google.com/permissions 进行撤消
GoogleUser.getAuthResponse()
GoogleUser.getBasicProfile() 凭据响应 直接使用 credential 和子字段，而不是 BasicProfile 方法。
GoogleUser.getgrantedScopes() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleUser.getHostedDomain() 凭据响应 而是直接使用 credential.hd。
GoogleUser.getId() 凭据响应 而是直接使用 credential.sub。
GoogleUser.grantofflineAccess() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleUser.grant() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleUser.hasgrantedScopes() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleUser.isSignedIn() 移除。无法获取用户在 Google 上的当前登录状态。 用户必须登录 Google 才能表示同意和完成登录。
GoogleUser.reloadAuthResponse() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2 对象和关联的方法：
gapi.auth2.AuthorizeConfig 对象 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.AuthorizeResponse 对象 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.AuthResponse 对象 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.authorize() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.ClientConfig() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.getAuthInstance() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.init() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.offlineAccessOptions 对象 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.auth2.SignInOptions 对象 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
gapi.signin2 对象和关联的方法：
gapi.signin2.render() 移除。加载 g_id_signin 元素的 HTML DOM 或对 google.accounts.id.renderButton 的 JS 调用会触发用户登录 Google 帐号。