从 Google 登录迁移

本指南可帮助您了解为实现上述目的而进行的必要更改和 从旧版 Google 登录服务成功迁移了 JavaScript 库 平台库迁移到新版 Google Identity Services 库， authentication。

如果您的客户端使用的是适用于 JavaScript 或其他 授权的早期库，请参阅迁移至 Google Identity 服务。

<ph type="x-smartling-placeholder">

身份验证和授权

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

与旧版 Google 登录平台库一样，新版 Google Identity 服务库旨在支持身份验证和授权 过程。

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

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

如果您的用例包括授权，请参阅用户授权的工作原理 并迁移到 Google Identity Services，确保您的应用 使用经过改进的全新 API。

具体变化

新的 Google Identity Services 库为用户提供了众多 易用性改进其特点包括：

  • 顺畅的全新一键式和自动登录流程，减少了用户数量 步数，
  • 焕然一新的登录按钮，提供用户个性化功能；
  • 在整个网络上进行一致的品牌宣传和统一的登录行为的改善 理解和信任，
  • 快速访问内容；用户可以从任何位置直接注册和登录 而不必先访问登录页或账号页，也可以访问您的网站。

对于开发者来说，我们的重点一直是降低复杂性、提高安全性， 让您的集成尽快完成。其中一些改进包括：

  • 您可以选择只使用 HTML、
  • 登录身份验证与授权和共享 因此不再需要进行复杂的 OAuth 2.0 集成 让用户登录您的网站
  • 系统仍继续支持弹出式和重定向模式 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 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 测试阶段，然后再在生产环境中使用。

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 登录按钮，以用户 连接到后端服务器登录端点。

<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>

已渲染

使用 visual-attributes 自定义“使用 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 网站。

以交互方式查看按钮自定义选项，例如回调类型和 属性（如颜色、尺寸、形状、文字和主题），请参阅我们的代码 generator。它可用于快速比较不同的选项 供您的网站使用的 HTML 代码段。

一键从任意页面登录

一键快捷功能为用户提供了一种顺畅的新网站注册或登录方式。 它可让用户直接从您网站上的任何页面登录， 使用户无需访问专门的登录页面。换句话说 这样可以让用户灵活选择 从登录页以外的页面注册和登录。

要从任何页面启用登录功能，我们建议您在任何页面添加 g_id_onload 您整个网站中包含的共享页眉、页脚或其他对象。

我们还建议您添加 g_id_signin，它会显示个性化登录选项 按钮。为用户提供选择 以通过在其他联盟应用旁边显示该按钮 “身份提供商”按钮以及用户名和密码输入字段。

令牌响应

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

系统会返回以下任一项安全且由 Google 签名的 JWT ID 令牌凭据：

  • 以弹出式窗口模式触发用户基于浏览器的 JavaScript 回调处理程序；或者
  • 从 Google 重定向到您的登录端点， “使用 Google 账号登录”按钮 ux_mode 已设为 redirect。

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

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

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

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

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

当用户首次登录您的网站时，Google 会提示用户同意 与您的应用分享其账号个人资料。只有在提供用户同意后， ID 令牌凭据载荷中分享给应用的用户个人资料。 撤消对此配置文件的访问权限等同于撤消 登录库

用户可以撤消权限并取消您的应用与其 Google 账号的关联 访问 https://myaccount.google.com/permissions。 用户也可能会通过触发 API 直接与您的应用断开连接 您实现的调用更早的 disconnect 方法 取而代之的是较新的 revoke 方法。

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

以前，可以使用 auth2.signOut() 来帮助管理用户退出 。应移除对 auth2.signOut() 的任何使用，并且您的应用 应直接管理每个用户会话的状态和登录状态。

会话状态和监听器

新版库不会保留您网站的登录状态或会话状态 应用。

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 服务库可以选择设置这些跨网域 Cookie：

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

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

    • 将 HTML API 与 data-ux_mode=redirect 或 data-login_uri 搭配使用时 设置，或者

    • 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() IdConfiguration.callback 适用于 JS 和 HTML 的 data-callback 替换为新服务。
GoogleAuth.currentUser.get() CredentialResponse 不再需要，请改用 CredentialResponse 。
GoogleAuth.currentUser.listen() 移除。无法获知用户当前在 Google 上的登录状态。 用户必须登录 Google 才能征得用户同意和登录。 通过 select_by CredentialResponse 中的 字段，可用于确定 以及所用的登录方法。
GoogleAuth.disconnect() google.accounts.id.revoke 替换为新服务。撤消也可能会访问 https://myaccount.google.com/permissions
GoogleAuth.grantOfflineAccess() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleAuth.isSignedIn.get() 移除。无法获知用户当前在 Google 上的登录状态。 用户必须登录 Google 才能征得用户同意和登录。
GoogleAuth.isSignedIn.listen() 移除。无法获知用户当前在 Google 上的登录状态。 用户必须登录 Google 才能征得用户同意和登录。
GoogleAuth.signIn() 移除。HTML DOM 加载 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() CredentialResponse 直接使用 credential 和子字段，而不是 BasicProfile 方法。
GoogleUser.getGrantedScopes() 移除。ID 令牌已取代 OAuth 2.0 访问令牌和范围。
GoogleUser.getHostedDomain() CredentialResponse 而是直接使用 credential.hd。
GoogleUser.getId() CredentialResponse 而是直接使用 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() 移除。HTML DOM 加载 g_id_signin 元素或 JS 调用 google.accounts.id.renderButton 触发用户登录 Google 账号。