从 Google Identity Toolkit 迁移到 Google Cloud Identity Platform

最新版本的 Google Identity Toolkit 已发布为 Identity Platform 和 Firebase Authentication。今后，Identity Toolkit 的功能工作将被冻结，所有新功能都将在 Identity Platform 和 Firebase Authentication 上完成。我们建议 Identity Toolkit 开发者在其应用可行后尽快迁移到这些平台。

新功能

与 Google Identity Toolkit 相比，Identity Platform 已经提供了显著的功能增强：

  • 新版管理控制台

    Identity Platform 提供新的开发者控制台，可让您查看、修改和删除用户；这对于调试登录和注册流程非常有用。借助控制台，您还可以配置身份验证方法和自定义电子邮件模板。

  • 新的身份验证方法

    Identity Platform 支持企业联合标准（例如 SAML 和 OIDC），可让您扩缩 SaaS 应用和服务。Identity Platform 还支持 GitHub、Microsoft、Yahoo 等提供方。 您可以使用匿名登录创建唯一的用户 ID，而无需要求用户完成任何登录或注册流程；这样一来，您就可以像对待普通用户一样进行经过身份验证的 API 调用。当用户决定注册帐号时，系统会以相同的用户 ID 保留所有 activity。对于服务器端购物车等场景或者您希望在通过注册流程发送用户之前吸引用户的其他应用，这非常有用。

  • 利用服务等级协议和 Cloud 支持自信地扩大规模

    Identity Platform 基于值得信赖的 Google 基础架构构建而成，提供服务等级协议和来自 Google Cloud 的支持。这意味着您可以信心十足地扩缩服务，并依赖 Google 提供所需的弹性、可用性和可伸缩性。

  • 访问所有 Firebase

    Firebase 是一个移动平台，可助您快速开发优质应用、扩大用户群并赚取更多收益。Firebase 由多种补充功能组成，您可以根据自己的需求组合搭配这些功能，包括用于以下用途的基础架构：移动分析、云消息传递、实时数据库、文件存储、静态托管、远程配置、移动崩溃报告和 Android 测试。

  • 界面更新

    我们根据 Google 的最新用户体验研究，完全重建了界面流程。这包括密码恢复、帐号关联、新/现有帐号消除歧义流程（通常需要很长时间来编写和调试）。它集成了 Android 上的 Smart Lock（密码专用），从而显著提升了参与该计划的应用的登录和注册转化率。它还支持轻松修改主题，以匹配您的应用；为最大限度提高可定制性，Android 和 iOS 版本已开源。

  • 简化服务器设置

    使用 Identity Toolkit 后，我们发现许多开发者选择不实现电子邮件恢复流程。这样一来，如果用户忘记了密码，就无法恢复其帐号。Identity Platform 可以向用户发送电子邮件验证、密码重置和更改密码的消息，并且可以轻松为用户自定义文本。此外，您不再需要托管用于托管重定向和完成密码更改操作的界面 widget。

  • 新 SDK

    现在，Identity Toolkit 的所有服务器 API 都可以在我们的每个客户端库（Android、iOS、Web）中以原生方式提供。开发者无需受制于固定的界面，就可以登录和注册新老用户、访问用户属性、关联、更新和删除帐号、重置密码，还能执行更多其他操作。如果您愿意，可以基于此 API 手动构建自己的整个登录流程和体验。

  • 移动应用的会话管理

    借助 Identity Toolkit，应用会根据 Identity Toolkit 中的初始身份验证事件创建自己的会话状态。Identity Platform 使用后端服务，该后端服务获取一个从身份验证事件中生成的刷新令牌，并将其交换成适用于 Android、iOS 和 JavaScript 的长达 1 小时的访问令牌。当用户更改密码后，刷新令牌将无法再生成新的访问令牌，因此系统会停用访问权限，直到用户在设备上重新进行身份验证。

功能差异

某些 Identity Toolkit 功能目前在 Identity Platform 中不可用，而其他功能已经过重新设计，其运作方式也有所不同。如果这些功能对您的应用很重要，您可以选择不立即迁移。在许多情况下，这些功能可能对您的应用并不重要，或者存在可让您继续迁移的简单回退。

服务器端差异

核心 Identity Toolkit 服务及其底层 REST API、帐号验证逻辑和主用户数据库只经历了细微的更新。但是，Identity Platform 中的某些功能以及将 Identity Platform 集成到服务中的方式已发生变化。

  • 身份提供方

    不支持 PayPal 和 AOL。使用来自这些 IDP 的帐号的用户仍然可以通过密码恢复流程登录您的应用，并为其帐号设置密码。

  • 服务器库

    目前，有适用于 Java、Node.js、Python、Go 和 C# 的 Admin SDK。

  • 帐号管理电子邮件

    密码重置、电子邮件验证和电子邮件更改消息可以由 Firebase 或开发者自己的邮件服务器执行。目前，电子邮件模板在界面上只能进行有限的自定义，但可以使用 Admin SDK 进一步自定义

  • 电子邮件地址变更确认

    在 Identity Toolkit 中，当用户决定更改其电子邮件地址时，它会向新地址发送一封电子邮件，其中包含继续执行电子邮件地址更改流程的链接。

    Firebase 通过向旧电子邮件地址发送撤消电子邮件以及用于还原更改的链接来确认电子邮件地址更改。

  • IDP 部署

    Identity Toolkit 能够将身份提供方逐步添加到您的登录系统，以便您可以试验对支持请求的影响。此功能已从 Firebase Authentication 中移除。

客户端差异

在 Identity Platform 中，Google Identity Toolkit 提供的功能分为两个组件：

  • 客户端 SDK 和服务器 SDK

    在 Identity Platform 中，Identity Toolkit 的 REST API 提供的功能已打包到适用于 Android、iOS 和 JavaScript 的客户端 SDK 中。您可以使用客户端 SDK 来登录和注册用户；访问用户个人资料信息；关联、更新和删除帐号；以及重置密码，而无需通过 REST 调用与后端服务进行通信。

  • 界面 widget

    所有管理登录、注册、密码恢复和帐号关联的界面流程都已使用客户端 SDK 重新构建，并打包为登录 widget。它们作为适用于 iOS、Android 和 Web 的开源 SDK 提供，可让您以 Identity Toolkit 无法实现的方式完全自定义这些流程。

其他区别包括：

  • 会话和迁移

    由于会话在 Identity Toolkit 和 Identity Platform 中的管理方式不同，因此用户的现有会话将在升级 SDK 时终止，而您的用户将必须重新登录。

准备工作

从 Identity Toolkit 迁移到 Identity Platform 之前，您必须完成以下操作：

  1. 打开 Cloud 控制台，选择您的 Identity Toolkit 项目。

  2. 在 Marketplace 中，浏览到 Identity Platform 并选择“启用 Identity Platform”

  3. 打开服务账号页面。您可以在此处看到之前为 Identity Toolkit 配置的服务帐号。

  4. 在相应服务帐号旁边，依次点击 > 创建密钥。然后，在创建私钥对话框中，将密钥类型设置为 JSON，然后点击创建。系统会为您下载包含服务帐号凭据的 JSON 文件。下一步需要用此文件初始化 SDK。

  5. 返回 Cloud 控制台。 在“提供商”部分的“电子邮件/密码”登录方法中，打开电子邮件模板页面。然后，您可以自定义应用的模板。

    在 Identity Toolkit 中，当用户重置密码、更改电子邮件地址或验证其电子邮件地址时，您需要从 Identity Toolkit 服务器获取 OOB 代码，然后通过电子邮件将该代码发送给用户。Identity Platform 根据您配置的模板发送电子邮件，无需执行任何其他操作。

  6. 可选：如果您需要在服务器上访问 Identity Platform 服务，请安装 Firebase SDK。

    1. 您可以使用 npm 安装 Node.js Admin SDK：

      $ npm init
$ npm install --save firebase-admin

    2. 在您的代码中，可以使用以下代码访问 Firebase：

      var admin = require('firebase-admin');
var app = admin.initializeApp({
  credential: admin.credential.cert('path/to/serviceAccountCredentials.json')
});

接下来，请针对您的应用平台（Android、iOS、Web）完成迁移步骤。

服务器和 JavaScript

显著变更

通过 Identity Toolkit 对 Identity Platform 进行 Web 实现还存在许多其他差异。

  • 网络会话管理

    以前，当用户使用 Identity Toolkit 微件进行身份验证时，系统会为用户设置 Cookie，用于引导会话。此 Cookie 的生命周期为两周，曾用于允许用户使用帐号管理 widget 更改密码和电子邮件地址。某些网站使用此 Cookie 对网站上的所有其他网页请求进行身份验证。其他网站则使用该 Cookie 通过其框架的 Cookie 管理系统创建自己的 Cookie。

    Identity Platform 客户端 SDK 现在可以管理 Id 令牌，并与 Identity Platform 的后端协同工作，使会话保持最新状态。在发生重要的帐号更改（例如用户密码更改）时，后端会让会话过期。ID 令牌不会自动设置为 Web 客户端上的 Cookie，其生命周期只有一小时。除非您只需要一小时的会话，否则不应将 ID 令牌用作 Cookie 来验证您的所有页面请求。而是需要针对用户的登录时间设置监听器，获取 ID 令牌，验证令牌，并通过框架的 Cookie 管理系统创建您自己的 Cookie。

    您需要根据应用的安全需求设置 Cookie 的会话生命周期。

  • Web 登录流程

    以前，用户会在登录时被重定向到 accountchooser.com，以了解用户想要使用的标识符。Identity Platform 界面的流程现在从登录方法列表开始，其中包括一个电子邮件选项，该选项在 Web 上转到 accountchooser.com，并在 Android 上使用 hintRequest API。此外，界面中不再需要电子邮件地址。这样可以更轻松地支持匿名用户、自定义身份验证用户或来自无需电子邮件地址的提供方的用户。

  • 帐号管理微件

    此微件提供了一个界面，供用户更改电子邮件地址、更改密码或解除其帐号与身份提供方的关联。它目前正在开发中。

  • 登录按钮/微件

    不再提供登录按钮和用户卡片等微件。您可以使用 Firebase Authentication API 非常轻松地构建这些功能。

  • 无 signOutUrl

    您需要调用 firebase.auth.signOut() 并处理回调。

  • 没有 oobActionUrl

    电子邮件发送现在由 Identity Platform 处理，并在 Firebase 控制台中进行配置。

  • CSS 自定义

    该界面 widget 使用 Material Design Lite 样式，这会动态添加 Material Design 动画。

第 1 步：更改服务器代码

  1. 如果您的服务器依赖 Identity Toolkit 令牌（有效期为两周）来管理 Web 用户会话，则您需要将该服务器转换为使用自己的会话 Cookie。

    1. 实现用于验证 ID 令牌和为用户设置会话 Cookie 的端点。客户端应用将 Firebase ID 令牌发送到此端点。
    2. 如果传入请求包含您自己的会话 Cookie，您可以考虑用户已通过身份验证。否则，请将请求视为未经身份验证。
    3. 如果您不希望任何用户丢失现有的登录会话，应该等待两周的所有 Identity Toolkit 令牌过期，或者同时为您的 Web 应用执行双令牌验证（如下文第 3 步所述）。

  2. 接下来，由于 Id 令牌与 Identity Toolkit 令牌不同，因此您必须更新令牌验证逻辑。将 Admin SDK 安装到服务器；或者，如果您使用 Admin SDK 不支持的语言，请下载适用于您的环境的 JWT 令牌验证库，并正确验证令牌。

  3. 首次进行上述更新时，您可能仍然有依赖于 Identity Toolkit 令牌的代码路径。如果您有 iOS 或 Android 应用，用户需要升级到该应用的新版本，新代码路径才能正常运行。如果您不想强制用户更新应用，则可以添加其他服务器验证逻辑，该逻辑会检查令牌并确定是使用 Firebase SDK 还是 Identity Toolkit SDK 来验证令牌。如果您只有 Web 应用，则所有新的身份验证请求都将转移到 Identity Platform，因此您只需使用 ID 令牌验证方法。

请参阅 Web API 参考文档。

第 2 步：更新 HTML

  1. 向您的应用添加初始化代码：

    1. 在 Cloud 控制台中打开您的项目。
    2. 在提供程序页面上，点击应用设置详情。系统会显示初始化 Identity Platform 的代码段。
    3. 将初始化代码段复制并粘贴到您的网页中。

  2. 将 Authentication widget 添加到您的应用中：

    <script src="https://www.gstatic.com/firebasejs/ui/live/0.4/firebase-ui-auth.js"></script>
<link type="text/css" rel="stylesheet" href="https://www.gstatic.com/firebasejs/ui/live/0.4/firebase-ui-auth.css" />
<!-- *******************************************************************************************
   * TODO(DEVELOPER): Paste the initialization snippet from:
   * Firebase Console > Overview > Add Firebase to your web app. *
   ***************************************************************************************** -->
<script type="text/javascript">
  // FirebaseUI config.
  var uiConfig = {
    'signInSuccessUrl': '<url-to-redirect-to-on-success>',
    'signInOptions': [
      // Leave the lines as is for the providers you want to offer your users.
      firebase.auth.GoogleAuthProvider.PROVIDER_ID,
      firebase.auth.FacebookAuthProvider.PROVIDER_ID,
      firebase.auth.TwitterAuthProvider.PROVIDER_ID,
      firebase.auth.GithubAuthProvider.PROVIDER_ID,
      firebase.auth.EmailAuthProvider.PROVIDER_ID
    ],
    // Terms of service url.
    'tosUrl': '<your-tos-url>',
  };

  // Initialize the FirebaseUI Widget using Firebase.
  var ui = new firebaseui.auth.AuthUI(firebase.auth());
  // The start method will wait until the DOM is loaded.
  ui.start('#firebaseui-auth-container', uiConfig);
</script>

  3. 从您的应用中移除 Identity Toolkit SDK。

  4. 如果您依赖 Identity Toolkit ID 令牌进行会话管理，则必须在客户端进行以下更改：

    1. 使用 Identity Platform 成功登录后，通过调用 firebase.auth().currentUser.getToken() 获取 ID 令牌。

    2. 将 ID 令牌发送到后端服务器，对其进行验证，并颁发您自己的会话 Cookie。

      在执行敏感操作或向您的服务器发送经过身份验证的修改请求时，请勿仅依赖会话 Cookie。您需要提供额外的跨网站请求伪造 (CSRF) 保护。

      如果您的框架未提供 CSRF 保护，一种防止攻击的方法是使用 getToken() 为已登录的用户获取 ID 令牌，并将该令牌添加到每个请求中（默认情况下，还会发送会话 Cookie）。然后，除了您的后端框架完成的会话 Cookie 检查之外，您还可以使用 Admin SDK 验证该令牌。这会使 CSRF 攻击更难成功，因为 ID 令牌仅使用网页存储空间进行存储，而不会存储在 Cookie 中。

    3. Identity Toolkit 令牌的有效期为两周。您可能希望继续颁发有效期为两周的令牌，也可以根据应用的安全要求增加或缩短令牌。当用户退出帐号时，清除会话 Cookie。

第 3 步：更新 IDP 重定向网址

  1. 在 Cloud 控制台中，打开提供商部分。

  2. 对于您支持的每个联合登录提供方，请执行以下操作：

    1. 点击登录提供方的名称。
    2. 复制 OAuth 重定向 URI。
    3. 在登录提供方的开发者控制台中，更新 OAuth 重定向 URI。

Android

第 1 步：使用 Firebase 将 Identity Platform 添加到您的应用

  1. 打开 Cloud Console，选择您的 Identity Toolkit 项目。

  2. 在“提供方”页面上，点击应用设置详情，选择 Android 标签页，然后点击 Get Started in Firebase。在“添加 Firebase”对话框中，提供应用的软件包名称和签名证书指纹，然后点击添加应用。然后，系统会将 google-services.json 配置文件下载到您的计算机。

  3. 将配置文件复制到 Android 应用模块的根目录。此配置文件包含项目和 Google OAuth 客户端信息。

  4. 在项目级 build.gradle 文件 (<var>your-project</var>/build.gradle) 的 defaultConfig 部分指定应用的软件包名称：

    defaultConfig {
   …..
  applicationId "com.your-app"
}

  5. 此外，在您的项目级 build.gradle 文件中，添加一个依赖项以包含 google-services 插件：

    buildscript {
 dependencies {
   // Add this line
   classpath 'com.google.gms:google-services:3.0.0'
 }
}

  6. 在应用的应用级 build.gradle 文件 (<var>my-project</var>/<var>app-module</var>/build.gradle) 中，在 Android Gradle 插件后面添加以下行以启用 google-services 插件：

    apply plugin: 'com.android.application'
// Add this line
apply plugin: 'com.google.gms.google-services'

    google-services 插件使用 google-services.json 文件将您的应用配置为使用 Firebase。

  7. 此外，在应用级 build.gradle 文件中，添加 Firebase Authentication 依赖项：

    compile 'com.google.firebase:firebase-auth:22.3.1'
compile 'com.google.android.gms:play-services-auth:21.0.0'

第 2 步：移除 Identity Toolkit SDK

  1. 从 AndroidManifest.xml 文件中移除 Identity Toolkit 配置。此信息包含在 google-service.json 文件中，并由 google-services 插件加载。
  2. 从您的应用中移除 Identity Toolkit SDK。

第 3 步：将 FirebaseUI 添加到您的应用

  1. 将 FirebaseUI Auth 添加到您的应用。

  2. 在您的应用中，将对 Identity Toolkit SDK 的调用替换为对 FirebaseUI 的调用。

iOS

第 1 步：将 Firebase 添加到您的应用

  1. 运行以下命令，将客户端 SDK 添加到您的应用中：

    $ cd your-project directory
$ pod init
$ pod 'Firebase'

  2. 打开 Cloud Console，选择您的 Identity Toolkit 项目。

  3. 在“提供商”页面上，点击应用设置详情，选择 iOS 标签页，然后点击 Get Started in Firebase。在“添加 Firebase”对话框中，提供应用的软件包名称和签名证书指纹，然后点击添加应用。然后，系统会将 google-services.json 配置文件下载到您的计算机。在“添加 Firebase”对话框中，提供应用的软件包 ID 和 App Store ID，然后点击添加应用。然后，系统会将 GoogleService-Info.plist 配置文件下载到您的计算机。如果您的项目中有多个软件包 ID，则必须在 Firebase 控制台中关联每个软件包 ID，以便它可以拥有自己的 GoogleService-Info.plist 文件。

  4. 将配置文件复制到 Xcode 项目的根目录并将其添加到所有目标。

第 2 步：移除 Identity Toolkit SDK

  1. 从应用的 Podfile 中移除 GoogleIdentityToolkit。
  2. 运行 pod install 命令。

第 3 步：将 FirebaseUI 添加到您的应用

  1. 将 FirebaseUI Auth 添加到您的应用。

  2. 在您的应用中，将对 Identity Toolkit SDK 的调用替换为对 FirebaseUI 的调用。