使用电话号码进行 Firebase 身份验证 (JavaScript)

使用 Firebase 身份验证，您可以向用户的电话发送短信协助其登录，用户使用短信中包含的一次性验证码即可登录。

如需向应用中添加电话号码登录方式，最简单的方法就是使用 FirebaseUI。该库中包含一个普适性登录 widget，可为电话号码登录、基于密码登录和联合登录实现登录流程。本文档介绍了如何使用 Firebase SDK 实现电话号码登录流程。

Google 会接收和存储最终用户为完成身份验证而提供的电话号码，以便各 Google 服务（包括但不限于 Firebase）更好地防范垃圾内容和滥用行为。在使用 Firebase Authentication 电话号码登录服务之前，开发者应确保已征得最终用户的同意。

准备工作

如果您尚未将初始化代码段从 Firebase 控制台复制到您的项目（如将 Firebase 添加到您的 JavaScript 项目中所述），请先执行此操作。

安全考量

与其他可用的方法相比，仅使用电话号码进行身份验证的方法虽然便捷，但安全性较低，因为电话号码的所有权可以很容易地在用户之间转移。此外，在具有多份用户个人资料的设备上，任何一位可以接收短信的用户都能使用该设备的电话号码登录帐号。

如果您选择在应用中使用电话号码登录方法，应同时提供更安全的登录方法，并将使用电话号码登录的安全隐患告知用户。

为 Firebase 项目启用电话号码登录方法

如需让用户能够通过短信登录，您必须先为 Firebase 项目启用电话号码登录方法，步骤如下：

1. 在 Firebase 控制台中，打开 Authentication 部分。
2. 在登录方法页面上，启用电话号码登录方法。
3. 在同一页面上，如果 OAuth 重定向网域部分未列出将托管您应用的网域，请添加您的网域。

Firebase 的电话号码登录请求的配额非常充足，大多数应用都不会遇到配额问题。但是，如果有大量用户需要通过电话号码身份验证方法进行登录，您可能需要升级定价方案。请参阅价格页面。

设置 reCAPTCHA 验证程序

在让用户使用其电话号码登录之前，您必须设置 Firebase 的 reCAPTCHA 验证程序。Firebase 使用 reCAPTCHA 来防止滥用行为，具体方法是确保电话号码验证请求来自应用允许的某个网域。

您无需手动设置 reCAPTCHA 客户端；在使用 Firebase SDK 的 RecaptchaVerifier 对象时，Firebase 会自动创建和处理任何必要的客户端密钥和密文。

RecaptchaVerifier 对象支持隐形 reCAPTCHA（通常用户无需进行任何操作便能验证身份）以及 reCAPTCHA widget（始终需要用户互动才能完成验证）。

在底层呈现的 reCAPTCHA 可以根据用户的偏好设置进行本地化，方法是在呈现 reCAPTCHA 之前更新 Auth 实例中的语言代码。发送给用户的短信（其中包含验证码）也会相应地进行本地化。

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

import { getAuth } from "firebase/auth";

const auth = getAuth();
auth.languageCode = 'it';
// To apply the default browser preference instead of explicitly setting it.
// auth.useDeviceLanguage();
auth_set_language_code.js

Web 命名空间型 API

firebase.auth().languageCode = 'it';
// To apply the default browser preference instead of explicitly setting it.
// firebase.auth().useDeviceLanguage();
index.js

使用隐形 reCAPTCHA

如需使用隐形 reCAPTCHA，请创建一个 RecaptchaVerifier 对象，将 size 参数设置为 invisible，并指定用于提交登录表单的按钮的 ID。例如：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

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

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'sign-in-button', {
  'size': 'invisible',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    onSignInSubmit();
  }
});
auth_phone_recaptcha_verifier_invisible.js

Web 命名空间型 API

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('sign-in-button', {
  'size': 'invisible',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    onSignInSubmit();
  }
});
phone-auth.js

使用 reCAPTCHA widget

如需使用可见的 reCAPTCHA widget，请在页面上创建一个包含此 widget 的元素，然后创建一个 RecaptchaVerifier 对象，并指定该容器的 ID。例如：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

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

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'recaptcha-container', {});
auth_phone_recaptcha_verifier_simple.js

Web 命名空间型 API

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container');
phone-auth.js

可选：指定 reCAPTCHA 参数

您可以选择为 RecaptchaVerifier 对象设置回调函数，以便在用户解答 reCAPTCHA 时或 reCAPTCHA 在用户提交表单前到期的情况下调用：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

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

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'recaptcha-container', {
  'size': 'normal',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    // ...
  },
  'expired-callback': () => {
    // Response expired. Ask user to solve reCAPTCHA again.
    // ...
  }
});
auth_phone_recaptcha_verifier_visible.js

Web 命名空间型 API

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container', {
  'size': 'normal',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    // ...
  },
  'expired-callback': () => {
    // Response expired. Ask user to solve reCAPTCHA again.
    // ...
  }
});
phone-auth.js

可选：预呈现 reCAPTCHA

如果您要在提交登录请求之前预呈现 reCAPTCHA，请调用 render：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

recaptchaVerifier.render().then((widgetId) => {
  window.recaptchaWidgetId = widgetId;
});
auth_phone_recaptcha_render.js

Web 命名空间型 API

recaptchaVerifier.render().then((widgetId) => {
  window.recaptchaWidgetId = widgetId;
});
phone-auth.js

render 解析完成后，您会获得 reCAPTCHA 的 widget ID，此 ID 可用于调用 reCAPTCHA API：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

const recaptchaResponse = grecaptcha.getResponse(recaptchaWidgetId);
auth_get_recaptcha_response.js

Web 命名空间型 API

const recaptchaResponse = grecaptcha.getResponse(recaptchaWidgetId);
phone-auth.js

向用户的电话发送验证码

如需启动电话号码登录，请向用户显示一个提示其输入电话号码的界面，然后调用 signInWithPhoneNumber 以请求 Firebase 通过短信向用户电话发送身份验证码：

1. 获取用户的电话号码。

   虽然相关的法律要求可能不尽相同，但为了避免用户不满，最佳做法是告知用户，如果他们选择使用电话号码登录方式，则可能会收到一条验证短信，并需按标准费率支付短信费用。

2. 调用 signInWithPhoneNumber，向其传递用户的电话号码和您之前创建的 RecaptchaVerifier。

   Web 模块化 API

   详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

   import { getAuth, signInWithPhoneNumber } from "firebase/auth";
   
   const phoneNumber = getPhoneNumberFromUserInput();
   const appVerifier = window.recaptchaVerifier;
   
   const auth = getAuth();
   signInWithPhoneNumber(auth, phoneNumber, appVerifier)
       .then((confirmationResult) => {
         // SMS sent. Prompt user to type the code from the message, then sign the
         // user in with confirmationResult.confirm(code).
         window.confirmationResult = confirmationResult;
         // ...
       }).catch((error) => {
         // Error; SMS not sent
         // ...
       });
   auth_phone_signin.js

   Web 命名空间型 API

   const phoneNumber = getPhoneNumberFromUserInput();
   const appVerifier = window.recaptchaVerifier;
   firebase.auth().signInWithPhoneNumber(phoneNumber, appVerifier)
       .then((confirmationResult) => {
         // SMS sent. Prompt user to type the code from the message, then sign the
         // user in with confirmationResult.confirm(code).
         window.confirmationResult = confirmationResult;
         // ...
       }).catch((error) => {
         // Error; SMS not sent
         // ...
       });
   phone-auth.js

   如果 signInWithPhoneNumber 导致错误，请重置 reCAPTCHA，以便用户重试：

   grecaptcha.reset(window.recaptchaWidgetId);
   
   // Or, if you haven't stored the widget ID:
   window.recaptchaVerifier.render().then(function(widgetId) {
     grecaptcha.reset(widgetId);
   });
   

   注意：您每天能够发送的短信数量可能存在一定配额限制，具体取决于您的结算方案。请参阅 Firebase Authentication 限额。

signInWithPhoneNumber 方法会向用户发起 reCAPTCHA 验证，如果用户通过该验证，则此方法会请求 Firebase Authentication 向用户电话发送一条含验证码的短信。

为了防止滥用，Firebase 对在一段时间内可以发送到单个电话号码的短信数量做了限制。如果超出此限制，电话号码验证请求可能会受限。如果您在开发期间遇到此问题，请使用其他电话号码进行测试，或稍后再次尝试该请求。

使用验证码让用户登录

成功调用 signInWithPhoneNumber 后，提示用户输入自己通过短信收到的验证码。然后，将此验证码传递给 ConfirmationResult 对象的 confirm 方法（该对象已被传递给 signInWithPhoneNumber 的履行处理程序，即它的 then 块），使用户登录到帐号。例如：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

const code = getCodeFromUserInput();
confirmationResult.confirm(code).then((result) => {
  // User signed in successfully.
  const user = result.user;
  // ...
}).catch((error) => {
  // User couldn't sign in (bad verification code?)
  // ...
});
auth_phone_verify_code.js

Web 命名空间型 API

const code = getCodeFromUserInput();
confirmationResult.confirm(code).then((result) => {
  // User signed in successfully.
  const user = result.user;
  // ...
}).catch((error) => {
  // User couldn't sign in (bad verification code?)
  // ...
});
phone-auth.js

如果成功调用 confirm，则表示用户已成功登录。

获取中间 AuthCredential 对象

如果您需要获取用户帐号的 AuthCredential 对象，请将确认结果返回的验证 ID 和相应验证码传递给 PhoneAuthProvider.credential，而不是调用 confirm：

var credential = firebase.auth.PhoneAuthProvider.credential(confirmationResult.verificationId, code);

然后，您可以使用该凭据让用户登录：

firebase.auth().signInWithCredential(credential);

使用虚构的电话号码进行测试

您可以通过 Firebase 控制台设置虚构电话号码以用于开发。使用虚构的电话号码进行测试具有以下优势：

• 测试电话号码身份验证时不会占用使用量配额。
• 测试电话号码身份验证时无需发送实际的短信。
• 可使用同一电话号码运行连续测试，而不会受到短信发送数量的限制。如果审核人员恰好使用相同的电话号码进行测试，这项优势会使在 App Store 审核过程中遭拒的风险降至最低。
• 无需其他操作即可在开发环境中轻松进行测试，例如可以在 iOS 模拟器或没有 Google Play 服务的 Android 模拟器中进行开发。
• 可编写集成测试，而不会被通常在生产环境中应用于真实电话号码的安全检查所屏蔽。

虚构的电话号码必须满足以下要求：

1. 请确保使用确属虚构且不存在的电话号码。Firebase Authentication 不允许您将真实用户使用的现有电话号码设为测试号码。您可以使用以 555 为前缀的数字作为美国测试电话号码，例如：[phone]
2. 电话号码必须采用正确的格式，以符合长度要求和其他限制。这些电话号码仍将与真实用户的电话号码一样经过相同的验证。
3. 您最多可以添加 10 个电话号码用于开发。
4. 使用难以猜到的测试电话号码/验证码，并经常更换。

创建虚构的电话号码和验证码

1. 在 Firebase 控制台中，打开 Authentication 部分。
2. 在 Sign in method（登录方法）标签页中，启用电话号码提供方（如果您尚未启用）。
3. 打开用于测试的电话号码折叠菜单。
4. 提供您想要用于测试的电话号码，例如 [phone]。
5. 为该特定号码提供 6 位验证码，例如 654321。
6. 添加该号码。如有需要，您可以删除电话号码及其验证码，只需将鼠标悬停在相应的行上并点击垃圾桶图标即可。

手动测试

您可以直接在应用中开始使用虚构的电话号码。这样一来，您就可以在开发阶段执行手动测试，而不会遇到配额问题或受到限制。您也可以直接通过 iOS 模拟器或未安装 Google Play 服务的 Android 模拟器进行测试。

当您提供虚构电话号码并发送验证码时，系统实际上不会发送短信。作为替代，您需要提供事先配置的验证码来完成登录。

完成登录后，系统会使用该电话号码创建一位 Firebase 用户。该用户的行为和属性与真实电话号码用户相同，并且可通过同样的方式使用 Realtime Database/Cloud Firestore 和其他服务。在此过程中生成的 ID 令牌与真实电话号码用户的令牌具有相同的签名。

由于虚构电话号码的 ID 令牌与真实电话号码用户的令牌具有相同的签名，请务必安全地存储这些号码并持续地重复利用。

您还可以利用自定义声明为此类用户设置测试角色，以将其作为虚构用户区分开来（如果您想进一步限制其访问权限）。

集成测试

除了手动测试外，Firebase Authentication 还提供了 API，帮助您编写用于进行电话号码身份验证测试的集成测试。这些 API 通过停用 reCAPTCHA 要求（在 Web 应用中）和静默推送通知（在 iOS 应用中）来停用应用验证。因此，您可以在这些流程中进行自动测试，并且实现起来更加容易。此外，借助这些 API，您还可以在 Android 上测试即时验证流程。

确保不要针对正式版应用停用应用验证，并且不要将任何虚构电话号码硬编码到您的正式版应用中。

在 Web 上，请将 appVerificationDisabledForTesting 设置为 true，然后再呈现 firebase.auth.RecaptchaVerifier。这会自动解析 reCAPTCHA，因此您无需手动解析即可传递电话号码。请注意，即使停用了 reCAPTCHA，使用非虚构电话号码也无法完成登录。此 API 只能使用虚构的电话号码。

// Turn off phone auth app verification.
firebase.auth().settings.appVerificationDisabledForTesting = true;

var phoneNumber = "[phone]";
var testVerificationCode = "123456";

// This will render a fake reCAPTCHA as appVerificationDisabledForTesting is true.
// This will resolve after rendering without app verification.
var appVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container');
// signInWithPhoneNumber will call appVerifier.verify() which will resolve with a fake
// reCAPTCHA response.
firebase.auth().signInWithPhoneNumber(phoneNumber, appVerifier)
    .then(function (confirmationResult) {
      // confirmationResult can resolve with the fictional testVerificationCode above.
      return confirmationResult.confirm(testVerificationCode)
    }).catch(function (error) {
      // Error; SMS not sent
      // ...
    });

停用应用验证后，可见和隐形的模拟 reCAPTCHA 应用验证程序的行为有所不同：

• 可见的 reCAPTCHA：当可见的 reCAPTCHA 通过 appVerifier.render() 呈现时，它会在不到一秒的延迟后自动解析。这相当于用户在呈现时立即点击 reCAPTCHA。reCAPTCHA 响应将在一段时间后过期，然后再次自动解析。
• 隐形 reCAPTCHA：隐形 reCAPTCHA 不会在呈现时自动解析，而会在 appVerifier.verify() 被调用或 reCAPTCHA 的按钮锚被点击后延迟不到一秒自动解析。同样，reCAPTCHA 响应也会在一段时间后过期，并且只会在 appVerifier.verify() 被调用或 reCAPTCHA 的按钮锚被再次点击后自动解析。

模拟 reCAPTCHA 每次得到解析时，系统都会按照预期触发相应的回调函数并给出虚假响应。如果还指定了 expiration 回调函数，则系统会在响应到期时触发此回调函数。

后续步骤

在用户首次登录后，系统会创建一个新的用户帐号，并将其与该用户登录时使用的凭据（即用户名和密码、电话号码或者身份验证提供方信息）相关联。此新帐号存储在您的 Firebase 项目中，无论用户采用何种方式登录，您项目中的每个应用都可以使用此帐号来识别用户。

• 在您的应用中，建议通过在 Auth 对象上设置观测者 (observer) 来了解用户的身份验证状态。然后，您便可从 User 对象获取用户的基本个人资料信息。请参阅管理用户。

• 在您的 Firebase Realtime Database 和 Cloud Storage 安全规则中，您可以从 auth 变量获取已登录用户的唯一用户 ID，然后利用此 ID 来控制用户可以访问哪些数据。

您可以将多个身份验证提供方凭据与一个现有用户帐号关联，让用户可以使用多个身份验证提供方登录您的应用。

如需让用户退出登录，请调用 signOut：

Web 模块化 API

详细了解可实现摇树优化的模块化 Web API，并从命名空间型 API 升级。

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

const auth = getAuth();
signOut(auth).then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
auth_sign_out.js

Web 命名空间型 API

firebase.auth().signOut().then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
index.js