获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

将您的应用程序连接到身份验证模拟器

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

在将身份验证模拟器与您的应用程序一起使用之前,请确保您了解整个 Firebase Local Emulator Suite 工作流程,并安装和配置Local Emulator Suite 并查看其CLI 命令

本主题假设您已经熟悉为生产环境开发 Firebase 身份验证解决方案。如果需要,请查看您的平台和身份验证技术组合的文档。

我可以使用身份验证模拟器做什么?

身份验证模拟器提供 Firebase 身份验证服务的高保真本地模拟,提供生产 Firebase 身份验证中的大部分功能。与 Apple 平台、Android 和 Web Firebase SDK 配对后,该模拟器可以让您:

  • 创建、更新和管理模拟用户帐户,用于测试电子邮件/密码、电话号码/SMS、SMS 多因素和第三方(例如 Google)身份提供者身份验证
  • 查看和编辑模拟用户
  • 原型定制令牌认证系统
  • 在模拟器 UI 日志选项卡中检查与身份验证相关的消息。

选择一个 Firebase 项目

Firebase Local Emulator Suite 模拟单个 Firebase 项目的产品。

要选择要使用的项目,请在启动模拟器之前,在 CLI 中运行firebase use在您的工作目录中使用。或者,您可以将--project标志传递给每个模拟器命令。

Local Emulator Suite 支持模拟真实的Firebase 项目和演示项目。

项目类型特征与模拟器一起使用
真实的

一个真正的 Firebase 项目是您创建和配置的项目(很可能是通过 Firebase 控制台)。

真实项目具有实时资源,例如数据库实例、存储桶、函数或您为该 Firebase 项目设置的任何其他资源。

在处理真实的 Firebase 项目时,您可以为任何或所有受支持的产品运行模拟器。

对于您未模拟的任何产品,您的应用程序和代码将与实时资源(数据库实例、存储桶、函数等)交互。

演示

一个演示 Firebase 项目没有真正的Firebase 配置,也没有实时资源。这些项目通常通过代码实验室或其他教程访问。

演示项目的项目 ID 具有demo-前缀。

使用演示 Firebase 项目时,您的应用程序和代码与模拟器交互。如果您的应用程序尝试与未运行模拟器的资源进行交互,则该代码将失败。

我们建议您尽可能使用演示项目。好处包括:

  • 设置更简单,因为您无需创建 Firebase 项目即可运行模拟器
  • 更强的安全性,因为如果您的代码不小心调用了非模拟(生产)资源,就没有数据更改、使用和计费的机会
  • 更好的离线支持,因为无需访问互联网即可下载您的 SDK 配置。

检测您的应用以与模拟器对话

Android、iOS 和网络 SDK

设置您的应用内配置或测试类以与身份验证模拟器交互,如下所示。

Kotlin+KTX
Firebase.auth.useEmulator("10.0.2.2", 9099)
Java
FirebaseAuth.getInstance().useEmulator("10.0.2.2", 9099);
迅速
Auth.auth().useEmulator(withHost:"localhost", port:9099)

Web version 9

import { getAuth, connectAuthEmulator } from "firebase/auth";

const auth = getAuth();
connectAuthEmulator(auth, "http://localhost:9099");

Web version 8

const auth = firebase.auth();
auth.useEmulator("http://localhost:9099");

无需额外设置即可对身份验证与 Cloud Functions 或 Cloud Firestore 或实时数据库的 Firebase 安全规则之间的交互进行原型设计和测试。当配置了身份验证模拟器并且其他模拟器正在运行时,它们会自动协同工作。

管理员 SDK

设置FIREBASE_AUTH_EMULATOR_HOST环境变量后,Firebase Admin SDK 会自动连接到身份验证模拟器。

export FIREBASE_AUTH_EMULATOR_HOST="localhost:9099"

请注意,Cloud Functions 模拟器会自动识别身份验证模拟器,因此您可以在测试 Cloud Functions 和身份验证模拟器之间的集成时跳过此步骤。将为 Cloud Functions 中的 Admin SDK 自动设置环境变量。

设置环境变量后,Firebase Admin SDK 将接受身份验证模拟器发出的未签名 ID 令牌和会话 cookie(分别通过verifyIdTokencreateSessionCookie方法)以促进本地开发和测试。请确保不要在生产环境中设置环境变量。

如果您希望您的 Admin SDK 代码连接到在另一个环境中运行的共享模拟器,您将需要指定您使用 Firebase CLI 设置的相同项目 ID 。您可以将项目 ID 直接传递给initializeApp或设置GCLOUD_PROJECT环境变量。

Node.js 管理 SDK
admin.initializeApp({ projectId: "your-project-id" });
环境变量
export GCLOUD_PROJECT="your-project-id"

身份证

出于安全原因,身份验证模拟器会发出未签名的 ID 令牌,只有其他 Firebase 模拟器或 Firebase Admin SDK 在配置时才接受这些令牌。这些令牌将被在生产模式下运行的生产 Firebase 服务或 Firebase Admin SDK 拒绝(例如,没有上述设置步骤的默认行为)。

启动模拟器

您可以通过 Emulator Suite UI 以交互方式使用身份验证模拟器,也可以通过其本地 REST 界面以非交互方式使用身份验证模拟器。以下部分涵盖交互式和非交互式用例。

要启动 Authentication 模拟器、它的 REST 接口和 Emulator Suite UI,请执行:

firebase emulators:start

对于匿名身份验证,您的应用程序可以为您的平台( iOSAndroidWeb )执行登录逻辑。

对于电子邮件/密码身份验证,您可以通过使用身份验证 SDK 方法或使用模拟器套件 UI 从您的应用程序将用户帐户添加到身份验证模拟器来开始原型制作。

  1. 在 Emulator Suite UI 中,单击身份验证选项卡。
  2. 单击添加用户按钮。
  3. 按照用户帐户创建向导,填写电子邮件身份验证字段。

创建测试用户后,您的应用程序可以使用适用于您的平台( iOSAndroidWeb )的 SDK 逻辑让用户登录和注销。

为了使用电子邮件链接流测试电子邮件验证/登录,模拟器将 URL 打印到执行firebase emulators:start的终端。

i  To verify the email address customer@ex.com, follow this link:
http://localhost:9099/emulator/action?mode=verifyEmail&lang=en&oobCode=XYZ123&apiKey=fake-api-key

将链接粘贴到浏览器中模拟验证事件,查看验证是否成功。

{
  "authEmulator": {
    "success": "The email has been successfully verified.",
    "email": "customer@example.com"
  }
}

为了测试密码重置,模拟器会向终端打印一个类似的 URL,其中包括一个newPassword参数(您可以根据需要更改该参数)。

http://localhost:9099/emulator/action?mode=resetPassword&oobCode=XYZ!23&apiKey=fake-api-key&newPassword=YOUR_NEW_PASSWORD

非交互式测试

您可以编写调用 REST API 的测试设置脚本来创建和删除用户帐户,并获取带外电子邮件验证代码以填充模拟器电子邮件验证,而不是使用 Emulator Suite UI 或客户端代码来管理电子邮件/密码用户帐户网址。这使平台和测试代码保持分离,并允许您进行非交互式测试。

对于非交互式电子邮件和密码测试流程,典型顺序如下。

  1. 使用 Authentication signUp REST 端点创建用户。
  2. 使用电子邮件和密码登录用户以执行测试。
  3. 如果适用于您的测试,请从特定于模拟器的 REST 端点获取可用的带外电子邮件验证码。
  4. 使用特定于模拟器的 REST 端点刷新用户记录以清除数据。

模拟电话/短信认证

对于手机身份验证,Auth 模拟器不支持:

  • reCAPTCHA 和 APN 流。一旦配置为与模拟器交互,客户端 SDK 就会以类似于集成测试( iOSAndroidWeb )所描述的方式禁用这些验证方法。
  • 使用 Firebase 控制台中预配置的代码测试电话号码。

否则,就客户端代码而言,电话/SMS 身份验证流程与生产环境( iOSAndroidWeb )中描述的相同。

使用模拟器套件用户界面:

  1. 在 Emulator Suite UI 中,单击身份验证选项卡。
  2. 单击添加用户按钮。
  3. 按照用户帐户创建向导,填写电话验证字段。

但是,对于电话身份验证流程,模拟器不会触发任何文本消息的传递,因为联系运营商超出范围并且不利于本地测试!相反,模拟器会打印出本应通过 SMS 发送到您运行firebase emulators:start的同一终端的代码;将此代码输入应用程序以模拟用户检查他们的短信。

非交互式测试

对于非交互式电话身份验证测试,请使用身份验证模拟器 REST API 检索可用的 SMS 代码。请注意,每次启动流程时代码都不同。

典型的顺序如下。

  1. 调用平台signInWithPhoneNumber启动验证过程。
  2. 使用特定于模拟器的 REST 端点检索验证码。
  3. 像往常一样用验证码调用confirmationResult.confirm(code)

多因素短信

身份验证模拟器支持原型设计和测试在iOSAndroidweb的生产中可用的 SMS 多因素身份验证 (MFA) 流。

当您将模拟用户添加到模拟器时,您可以启用 MFA 并配置一个或多个电话号码,第二因素 SMS 消息将发送到这些电话号码。消息输出到您运行firebase emulators:start的同一终端,并可从 REST 界面访问。

模拟第三方身份提供者 (IDP) 身份验证

身份验证模拟器让您可以在 iOS、Android 或 Web 应用程序中测试许多第三方身份验证流程,而无需更改生产代码。有关身份验证流程的示例,请参阅有关可在您的应用程序中使用的提供程序和平台的各种组合的文档。

一般来说,您可以使用 Firebase SDK 通过以下两种方式之一进行身份验证:

  • 您的应用程序让 SDK 处理端到端的整个过程,包括与第三方 IDP 提供商的所有交互以检索凭据。
  • 您的应用程序使用第三方的 SDK 从第三方提供商手动检索凭据,并将这些凭据传递给 Authentication SDK。

再次检查上面的文档链接,确保您熟悉您要使用的任何流程——Firebase SDK 管理的凭证检索与手动凭证检索。身份验证仿真器支持测试任一方法。

测试 Firebase SDK 驱动的 IDP 流

如果您的应用程序使用任何 Firebase SDK 端到端流程(例如用于登录 Microsoft、GitHub 或 Yahoo 的OAuthProvider )进行交互式测试,则身份验证模拟器会提供相应登录页面的本地版本来帮助您进行测试来自调用signinWithPopupsignInWithRedirect方法的 Web 应用程序的身份验证。这个本地服务的登录页面也出现在移动应用程序中,由您平台的 webview 库呈现。

随着流程的进行,模拟器会根据需要创建模拟的第三方用户帐户和凭据。

使用手动凭证检索测试 IDP 流程

如果您使用“手动”登录技术并调用平台的signInWithCredentials方法,那么您的应用程序将像往常一样请求真实的第三方登录并检索真实的第三方凭据。

请注意,模拟器仅支持对从 Google 登录、Apple 和其他使用作为 JSON Web 令牌 (JWT) 实现的 ID 令牌的提供商检索的凭据进行signInWithCredential身份验证。不支持访问令牌(例如 Facebook 或 Twitter 提供的那些,它们不是 JWT)。下一节将讨论这些情况下的替代方案。

非交互式测试

非交互式测试的一种方法是自动执行用户在模拟器提供的登录页面上的点击。对于网络应用程序,请使用像 WebDriver 这样的控制界面。对于移动设备,使用您平台上的 UI 测试工具,例如 Espresso 或 Xcode。

或者,您可以更新您的代码以使用signInWithCredential (例如,在代码分支中)并使用带有模拟 ID 令牌的令牌身份验证流程来代替真实凭据。

  1. 重新连接或注释掉从 IDP 检索 idTokens 的代码部分;这消除了在测试期间输入真实用户名和密码的需要,并使您的测试免受 IDP 的 API 配额和速率限制。
  2. 其次,使用文字 JSON 字符串代替signInWithCredential的令牌。以web SDK为例,可以将代码改成:
firebase.auth().signInWithCredential(firebase.auth.GoogleAuthProvider.credential(
  '{"sub": "abc123", "email": "foo@example.com", "email_verified": true}'
));

当与模拟器一起使用时,此代码将成功验证电子邮件foo@example.com在 Google 的用户。将子字段视为主键,可以更改为任何字符串,模拟不同用户的签名。例如,您可以将firebase.auth.GoogleAuthProvider替换为new firebase.auth.OAuthProvider('yahoo.com')或您想要模拟的任何其他提供商 ID。

模拟自定义令牌身份验证

身份验证模拟器通过在支持的平台上调用signInWithCustomToken方法来处理自定义 JSON Web 令牌的身份验证,如生产身份验证文档中所述。

身份验证模拟器与生产环境有何不同

Firebase 身份验证模拟器模拟生产产品的许多功能。但是,由于任何类型的身份验证系统都严重依赖多个级别(设备、第 3 方提供商、Firebase 等)的安全性,因此模拟器很难正确地重新创建所有流程。

云 IAM

Firebase 模拟器套件不会尝试复制或遵守任何与 IAM 相关的运行行为。模拟器遵守提供的 Firebase 安全规则,但在通常使用 IAM 的情况下,例如设置 Cloud Functions 调用服务帐户和权限,模拟器不可配置,将使用开发人员计算机上的全局可用帐户,类似于直接运行本地脚本。

由于在移动平台上,电子邮件链接登录依赖于 Firebase 动态链接,因此所有此类链接都将在(移动)网络平台上打开。

第三方登录

对于第三方登录流程,Firebase 身份验证依赖于来自 Twitter 和 Github 等第三方提供商的安全凭证。

身份验证模拟器接受来自 OpenID Connect 提供商(例如 Google 和 Apple)的真实凭据。不支持来自非 OpenID Connect 提供商的凭据。

电子邮件/短信登录

在生产应用程序中,电子邮件和 SMS 登录流程涉及异步操作,在该操作中,用户检查收到的消息并将登录代码输入登录界面。身份验证模拟器不发送任何电子邮件或 SMS 消息,但如上所述,它会生成登录代码并将它们输出到终端以用于测试。

模拟器不支持使用固定登录代码定义测试电话号码的功能,这可以使用 Firebase 控制台完成。

自定义令牌认证

身份验证模拟器不会验证自定义令牌的签名或过期时间。这允许您在原型设计和测试场景中使用手工制作的令牌并无限期地重复使用令牌。

速率限制/反滥用

身份验证模拟器不会复制生产速率限制或反滥用功能。

接下来是什么?