从 Google 登录服务迁移

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本指南可帮助您了解必要的更改和步骤，以便成功将 JavaScript 库从旧版 Google 登录平台库迁移到新版 Google Identity Services 库，从而实现身份验证。

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

身份验证和授权

身份验证可证明某人的身份，通常称为用户注册或登录。授权是授予或拒绝对数据或资源的访问权限。例如，您的应用请求用户同意访问其 Google 云端硬盘。

与旧版 Google 登录平台库一样，新的 Google Identity Services 库也是为了支持身份验证和授权流程。

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

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

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

具体变化

对用户而言，新的 Google Identity Services 库提供了多项易用性改进。其特点包括：

  • 全新的一键式体验和自动登录流程更加顺畅，个别步骤更少
  • 带有用户个性化功能的刷新登录按钮
  • 一致的品牌信息和统一的登录行为有助于 增进用户理解和信任
  • 快速访问内容；用户可以从您网站的任意位置直接轻松地登录和登录，而无需事先访问登录页或帐号页面。

对开发者而言，我们一直致力于降低复杂性、提高安全性，并使集成尽可能快速简单。其中一些改进包括：

  • 让用户仅使用 HTML 向您网站的静态内容添加登录信息，
  • 将登录身份验证与授权和共享用户数据分开，再也不需要进行复杂的 OAuth2 集成，只需让用户登录您的网站即可。
  • 弹出式窗口和重定向模式仍受支持，但 Google 的 OAuth2 基础架构现在会重定向到后端服务器的登录端点
  • 将来自旧版 Google Identity JavaScript 库和 Google API JavaScript 库的功能整合到一个新库中
  • 对于登录响应，您现在可以决定是否使用 promise，并且为了简单起见，移除了通过 getter 样式函数间接调用。

登录迁移示例

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

库和配置

用户身份验证和授权不再需要旧版 Google 登录平台库 apis.google.com/js/platform.js 和适用于 JavaScript 的 Google API 客户端库：gapi.client。它们已被替换为一个新的 Google Identity Services 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 客户端 ID 类型为“Web 应用”，以及
  • 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，然后再在生产环境中使用该 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 API 和 JavaScript API。

如需以交互方式查看按钮自定义选项（例如颜色、大小、形状、文本和主题等回调类型和属性），请查看代码生成器。 该文件可用于快速比较不同的选项，并生成用于您网站的 HTML 代码段。

只需点按一下，即可从任何页面登录

一键恢复功能可让用户轻松注册或登录您的网站。 利用意见征求模式，您可以直接从您网站上的任何页面启用用户登录功能，而无需用户访问专用的登录页面。换个说法，这种方法可以让用户更加灵活地登录和从您的登录页面进行登录，从而减少注册和登录问题。

若要从任意页面登录，我们建议您在整个网站的共享页眉、页脚或其他对象中添加 g_id_onload。

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

令牌响应

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

会返回由 Google 签名的安全 JWT ID 令牌凭据，可生成以下任一凭据：

  • 在弹出模式下发送到用户的基于浏览器的 JavaScript 回调处理程序，或者
  • 当“使用 Google 帐号登录”按钮 ux_mode 设置为 redirect 时，通过 Google 重定向到登录端点来发送到后端服务器。

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

  • 对 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 的所有引用。

Cookie

“使用 Google 帐号登录”功能对 Cookie 的使用有限制，下文介绍了对这些 Cookie 的说明。如需详细了解 Google 使用的其他类型的 Cookie，请参阅 Google 如何使用 Cookie。

不再使用旧版 Google 登录平台库设置的 G_ENABLED_IDPS Cookie。

新的 Google Identity Services 库可能会根据您的配置选项设置以下跨网域 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.attachClickHandler() 适用于 JS 和 HTML data-callback 的 IdConfiguration.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.grantofflineAccess() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
GoogleAuth.isSignedIn.get() 移除。用户当前在 Google 上的登录状态不可用。 用户必须登录 Google 才能征得用户同意和登录。
GoogleAuth.isSignedIn.listen() 移除。用户当前在 Google 上的登录状态不可用。 用户必须登录 Google 才能征得用户同意和登录。
GoogleAuth.signIn() 移除。HTML 加载 g_id_signin 元素或 JS 调用 google.accounts.id.renderButton 会触发用户登录 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 令牌已取代 OAuth2 访问令牌和范围。
GoogleUser.getHostedDomain() 凭据响应 而是直接使用 credential.hd。
GoogleUser.getId() 凭据响应 而是直接使用 credential.sub。
GoogleUser.grantofflineAccess() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
GoogleUser.grant() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
GoogleUser.hasGrantedScopes() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
GoogleUser.isSignedIn() 移除。用户当前在 Google 上的登录状态不可用。 用户必须登录 Google 才能征得用户同意和登录。
GoogleUser.reloadAuthResponse() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2 对象和关联的方法：
gapi.auth2.AuthorizeConfig 对象 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.AuthorizeResponse 对象 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.AuthResponse 对象 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.authorized() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.ClientConfig() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.getAuthInstance() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.init() 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.OfflineAccessOptions 对象 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.auth2.SignInOptions 对象 移除。ID 令牌已取代 OAuth2 访问令牌和范围。
gapi.signin2 对象和关联的方法：
gapi.signin2.render() 移除。HTML 加载 g_id_signin 元素或 JS 调用 google.accounts.id.renderButton 会触发用户登录 Google 帐号。