为基于短信的身份验证启用短信话费欺诈防护

本文档介绍了如何使用 reCAPTCHA 保护 Identity Platform 基于短信的流程（例如手机和多重身份验证），防范短信话费欺诈（也称为短信注入攻击）。

概览

如果您的应用依赖于基于短信的流程进行身份验证，您可以在 Identity Platform 与 reCAPTCHA 集成过程中启用 reCAPTCHA 短信话费欺诈防护功能。启用后，当用户使用以下 phoneProvider 操作从您的应用或网站请求验证短信时，Identity Platform 会调用短信付费欺诈防范功能：

操作 方法
使用电话号码注册或登录 sendVerificationCode
注册多重身份验证 (MFA) 手机号码 mfaSmsEnrollment
使用手机号码登录多重身份验证 mfaSmsSignIn

然后，reCAPTCHA 会向 Identity Platform 提供风险评分，该评分表示用户的手机号码实施短信话费欺诈的可能性。Identity Platform 会将此得分与您在短信话费欺诈防护配置中设置的阈值进行比较，然后根据您在配置中设置的操作处理请求。

如需详细了解 reCAPTCHA 短信话费欺诈防护功能，请参阅检测和防范短信欺诈。

准备工作

在为 Identity Platform 启用短信话费欺诈防护之前，请完成以下任务：

  • 根据需要为您的应用或网站配置以下内容：

  • 如果您还没有为将要使用 reCAPTCHA 的每个项目创建服务账号，请先创建服务账号。如需查看相关说明，请参阅创建服务账号。

reCAPTCHA 手机身份验证强制执行模式

若要使用 reCAPTCHA 短信话费欺诈防护功能，您必须设置 reCAPTCHA 手机身份验证强制执行，该功能有两种模式：审核和强制执行。

审核模式

当您将手机身份验证强制执行设置为审核模式时，Identity Platform 会使用 reCAPTCHA 短信话费欺诈防护功能进行应用验证。如果用户请求通过了话费欺诈评估，Identity Platform 会向用户的手机发送一条包含验证码的短信。如果请求未通过手机费欺诈评估，并且您使用的是客户端 SDK，系统会触发后备验证方法来完成手机身份验证流程。接受的回退方法取决于应用的平台。

客户端 SDK 会在以下情况下触发回退验证方法：

  • reCAPTCHA 令牌缺失。
  • reCAPTCHA 令牌无效或已过期。
  • reCAPTCHA 令牌未达到得分阈值。
  • reCAPTCHA 未正确配置。

确保已为应用的平台设置回退验证方法，并准备好在必要时由客户端 SDK 触发。

Web

如果初始的过路费欺诈评估失败，审核模式将依赖 reCAPTCHA v2 进行验证。因此，您必须设置 reCAPTCHA 验证程序 (RecaptchaVerifier)，并将其传递给以下手机身份验证操作：

  • verifyPhoneNumber
  • signInWithPhoneNumber
  • linkWithPhoneNumber
  • reauthenticateWithPhoneNumber
如果没有 reCAPTCHA 验证程序，Identity Platform 将无法启动 reCAPTCHA v2，并会返回 auth/argument-error。如需详细了解如何设置 reCAPTCHA 验证程序，请参阅 Firebase 文档中的设置 reCAPTCHA 验证程序。

Android

如果初始的过路费欺诈评估失败，审核模式会通过 Play Integrity API 验证您的应用。如果此验证失败，系统会触发 reCAPTCHA v2。 reCAPTCHA v2 可能会在以下场景中触发：

  • 如果最终用户的设备未安装 Google Play 服务。
  • 如果相关应用未通过 Google Play 商店分发（针对 Authentication SDK 21.2.0 及更高版本）。
  • 如果获得的 SafetyNet 令牌无效（针对 21.2.0 之前的 Authentication SDK 版本）。
如需详细了解如何设置 Android 应用验证，请参阅 Firebase 文档中的启用应用验证。

iOS

如果初始的过路费欺诈评估失败，审核模式将依赖于静默推送通知进行验证。此验证方法涉及使用静默推送通知向请求设备上的应用发送令牌。如果您的应用成功收到通知，手机身份验证流程会继续。如果您的应用未收到推送通知，系统会触发 reCAPTCHA v2。 如果未正确配置静默推送通知，系统可能会触发 reCAPTCHA v2。

如需详细了解如何设置 iOS 应用验证，请参阅 Firebase 文档中的启用应用验证。

强制模式

当您将手机身份验证强制执行设置为强制模式时，Identity Platform 会使用 reCAPTCHA 短信话费欺诈防护功能进行应用验证。如果用户请求通过了过路费欺诈评估，Identity Platform 会向用户的手机发送一条包含验证码的短信。如果请求未通过过路费欺诈评估，Identity Platform 会屏蔽该请求，并且不会发送包含验证码的短信。

强制执行模式不需要回退验证，因此您无需为应用设置任何其他验证方法。不过，如果您决定将应用的 reCAPTCHA 模式更改为 AUDIT 或 OFF，我们建议您为 Web 应用设置 reCAPTCHA 验证器，以确保启用 reCAPTCHA v2。

启用 reCAPTCHA 短信话费欺诈防护

如需启用短信话费欺诈防护，请执行以下操作：

  1. 如果尚未执行此操作，请为您的项目启用 reCAPTCHA Enterprise API。

  2. 使用 reCAPTCHA 启用短信话费欺诈防护。如需查看相关说明，请参阅 reCAPTCHA 文档中“检测和防范短信欺诈”页面的准备工作部分。

  3. 如需为项目启用短信话费欺诈防护，请使用 Admin SDK 调用 updateConfig，如下所示：

      // Update the reCAPTCHA config to enable toll fraud protection
  const updateProjectConfigRequest = {
    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE_MODE',
      useSmsTollFraudProtection: 'true',
      tollFraudManagedRules: [{ startScore: START_SCORE,
        action: 'BLOCK' }],
    }
  }
  let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);

    替换以下内容：

    • ENFORCE_MODE：您要为 reCAPTCHA 手机身份验证强制执行设置的模式。有效值为 OFF、AUDIT 和 ENFORCE。如需启用短信话费欺诈防护功能，此参数必须设置为 AUDIT 或 ENFORCE，并且 useSmsTollFraudProtection 必须设置为 true。

      首次启用短信话费欺诈防护功能时，我们建议您先将强制执行状态设置为 AUDIT，确保您的身份验证流程受到保护，然后再将其设置为 ENFORCE。如需详细了解这些模式的运作方式，请参阅 reCAPTCHA 手机身份验证强制执行模式。

    • START_SCORE：请求在失败之前可以达到的最高过路费欺诈评估得分。您可以将此得分设置为介于 0.0 和 1.0 之间。得分高于您设定的阈值的任何请求都将被视为短信付费欺诈。例如，如果您将阈值设置为 0.3，reCAPTCHA 将拒绝得分为 0.4 或更高的任何请求。因此，您设置的分数越低，规则就越严格。

  4. 如果您在 Web 或 Android 上使用 Identity Platform，请通过 Firebase 控制台注册您的应用：

    reCAPTCHA 密钥预配可能需要几分钟时间才能完成。

  5. 如果您已将强制执行设置为审核模式，我们建议您监控 reCAPTCHA 短信话费欺诈防护指标，以确保您的流程受到保护。

配置客户端 SDK

根据应用的平台配置客户端 SDK。

Web

  1. 更新到最新版本的 Web SDK。

    • JavaScript SDK 9.20.0 及更高版本支持在 Web 应用中使用 reCAPTCHA 进行电子邮件和密码身份验证。
    • JavaScript SDK 11 及更高版本支持在 Web 应用中使用 reCAPTCHA 进行手机验证。

    将 Web SDK 与应用集成后，该 SDK 会自动提取您的 reCAPTCHA 配置，并为您配置的提供方启用保护。

  2. 如果需要，您可以强制提取 reCAPTCHA 信号，如下所示：

    import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Authentication
const auth = getAuth();
initializeRecaptchaConfig(auth)
  .then(() => {
    console.log("Recaptcha Enterprise Config Initialization successful.")
  })
  .catch((error) => {
    console.error("Recaptcha Enterprise Config Initialization failed with " + error)
  });

Android

  1. 请更新到最新版 Android SDK。Android SDK 23.1.0 及更高版本支持在 Android 应用中对电子邮件和密码身份验证以及手机身份验证使用 reCAPTCHA。

    此外，若要支持 reCAPTCHA，则需要 API 级别 23 (Marshmallow) 或更高级别以及 Android 6 或更高版本。

    将 Android SDK 与您的应用集成后，该 SDK 会自动提取您的 reCAPTCHA 配置，并为您配置的提供程序启用保护。

  2. 将以下构建规则添加到应用级 build.gradle 文件的依赖项部分：

    implementation 'com.google.android.recaptcha:recaptcha:18.5.1'

    请务必使用 reCAPTCHA SDK 18.5.1 或更高版本。

  3. 如果需要，您可以强制提取 reCAPTCHA 信号，如下所示：

    • Kotlin：
    // Initialize Firebase Authentication
auth = Firebase.auth

auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
    if (task.isSuccessful) {
        Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
    } else {
        Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
    }
}
    • Java：
    // Initialize Firebase Authentication
auth = FirebaseAuth.getInstance();
auth.initializeRecaptchaConfig().addOnCompleteListener(
  this, new OnCompleteListener<void>() {
  @Override
  public void onComplete(@NonNull Task<void> task) {
    if (task.isSuccessful()) {
      Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
    } else {
      Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
    }
  }
});

iOS

  1. 更新到 iOS SDK 11.6.0 或更高版本。 将 iOS SDK 与您的应用集成后，SDK 会自动提取您的 reCAPTCHA 配置，并为您配置的提供程序启用保护。

  2. 如需将 reCAPTCHA iOS SDK 集成到您的应用，请参阅准备环境。

  3. 确保链接器标志中列出了 -ObjC。依次前往目标 > 构建设置 > 所有 > 链接，然后验证 Other Linker Flags 是否显示 -ObjC。

  4. 如果需要，您可以强制提取 reCAPTCHA 信号，如下所示：

    • Swift：
    // Initialize Firebase Authentication
try await Auth.auth().initializeRecaptchaConfig()
    • Objective-C：
    // Initialize Firebase Authentication
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Authentication initialization finished
}];

监控 reCAPTCHA 短信话费欺诈防护指标

在将 reCAPTCHA 强制执行设置为强制执行模式之前，我们建议您使用审核模式并监控项目发出的 reCAPTCHA 指标，以确保基于短信的身份验证流程受到保护。例如，这些指标可帮助您确定是否已正确设置 Identity Platform 与 reCAPTCHA Enterprise API 的集成。它们还可以帮助您微调用户流量的得分阈值。

通过检查您的项目向 Cloud Monitoring 发出的以下指标，确保短信过路费欺诈防范功能正常运行：

如需了解详情，请参阅监控 reCAPTCHA 指标。

强制执行短信话费欺诈防护

在验证您的应用正在接收可接受的用户流量后，您可以启用 reCAPTCHA 强制执行功能来保护您的用户。确保不会干扰现有用户，包括可能使用旧版应用的用户。

如需为项目或租户中的基于短信的身份验证流程启用 reCAPTCHA 强制执行，请使用 Admin SDK 运行以下命令：

  const enforceRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }
  };

停用短信话费欺诈防护

如需停用短信过路费欺诈防范功能，请使用 Admin SDK 运行以下命令：

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }
  };

如需在使用聊天机器人防护功能时停用短信话费欺诈防护，请参阅在使用聊天机器人防护功能时停用短信话费欺诈防护。

将短信话费欺诈防护与聊天机器人防护搭配使用

您可以同时使用短信话费欺诈防护和聊天机器人防护。对于同时使用这两项保护功能的配置，请考虑以下事项：

  • 如果您将手机身份验证强制执行状态设为“审核”，当请求满足至少一项评估时，Identity Platform 会将其通过。我们建议您监控 reCAPTCHA 指标，以确保短信话费欺诈防护和漫游器防护的得分设置合理。
  • 当您将手机身份验证强制执行状态设为“强制执行”时，Identity Platform 仅在请求同时满足这两项评估且请求失败关闭且未回退到其他验证方法时才会通过该请求。

如需启用这两项功能，请使用 Admin SDK 运行以下命令：

  const enableBothRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: true,
      useSmsBotScore: true
    }
  };

将 ENFORCE_MODE 替换为您要为 reCAPTCHA 手机身份验证强制执行设置的模式。有效值为 OFF、AUDIT 和 ENFORCE。如需启用短信话费欺诈防护，必须将此参数设置为 AUDIT 或 ENFORCE。首次启用短信付费欺诈防范功能时，我们建议您先将此参数设置为 AUDIT，并确保您的身份验证流程受到保护，然后再将其设置为 ENFORCE。如需详细了解这些模式的运作方式，请参阅 reCAPTCHA 手机身份验证强制执行模式。

停用短信话费欺诈防护，同时使用漫游器防护

如果您同时使用短信话费欺诈防护和聊天机器人防护，并且想要停用短信话费欺诈防护而不停用聊天机器人防护，请使用 Admin SDK 运行以下命令：

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }
  };

将 ENFORCE_MODE 替换为您之前为 reCAPTCHA 手机身份验证强制执行设置的模式。此值应为 AUDIT 或 ENFORCE。如需详细了解这些模式的运作方式，请参阅 reCAPTCHA 手机身份验证强制执行模式。

后续步骤