为基于短信的身份验证启用 reCAPTCHA SMS defense

本文档介绍了如何使用 reCAPTCHA SMS defense 来帮助保护基于 Identity Platform 短信的流程（例如手机和多重身份验证），防止遭受短信话费欺诈（也称为短信注入攻击）。此集成有助于防止未经授权的短信流量对您的用户和资源产生负面影响。

概览

如果您的应用依赖于短信进行身份验证，我们建议您启用 reCAPTCHA SMS defense 集成。启用后，每当最终用户使用以下 phoneProvider 操作从您的应用或网站请求验证短信时，Firebase Authentication 和 Identity Platform 都会自动调用 reCAPTCHA 短信防御功能：

操作 方法
使用电话号码注册或登录 sendVerificationCode
MFA 手机号码注册 mfaSmsEnrollment
MFA 手机号码登录 mfaSmsSignIn

然后，reCAPTCHA 会向 Firebase Authentication 或 Identity Platform 提供风险评分，该评分表示用户手机号码发生 SMS 滥用欺诈的可能性。然后，系统会将此得分与您配置的阈值进行比较。如果风险分数超过此阈值，系统将不会发送短信，从而有效阻止欺诈尝试。

如需了解 reCAPTCHA 短信防御得分的运作方式，请参阅解读得分。

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

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

您可以为 reCAPTCHA SMS defense 配置手机身份验证强制执行，以使用审核或强制执行模式。

审核模式

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

在以下情况下，客户端 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

如果初始的 Toll Fraud 评估失败，审核模式会根据 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

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

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

强制模式

当您将手机身份验证强制执行模式设置为“强制执行”模式时，Identity Platform 会使用 reCAPTCHA 短信防御机制进行应用验证。如果用户请求通过了话费欺诈评估，系统会发送短信验证码。如果用户请求未通过话费欺诈评估，Identity Platform 会阻止该请求，并且不会发送包含验证码的短信。

在强制执行模式下，无需进行回退验证，您无需为应用设置任何其他验证方法。不过，我们建议为 Web 应用设置 reCAPTCHA 验证器，以确保在您决定将应用的 reCAPTCHA 模式更改为 AUDIT 或 OFF 时，reCAPTCHA v2 处于启用状态。

准备工作

在为 Identity Platform 启用 reCAPTCHA SMS defense 之前，请完成以下任务：

启用 reCAPTCHA SMS defense

  1. 设置身份验证：

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

    2. 创建服务身份：

      gcloud beta services identity create \
    --service=identitytoolkit.googleapis.com \
    --project=PROJECT_ID

      将 PROJECT_ID 替换为项目 ID。

    3. 将 roles/identitytoolkit.serviceAgent 角色授予您创建的服务身份。

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
    --role=roles/identitytoolkit.serviceAgent

    替换以下内容：

    • PROJECT_ID：项目 ID
    • PROJECT_NUMBER：项目账号

  2. 为项目启用 reCAPTCHA Enterprise API。

  3. 为您的项目启用 reCAPTCHA SMS defense：

    1. 在 Google Cloud 控制台中，前往 reCAPTCHA 页面。

      前往 reCAPTCHA

    2. 验证项目名称是否显示在资源选择器中。

      如果您没有看到项目名称，请点击资源选择器，然后选择您的项目。

    3. 点击 设置。

    4. 在 SMS 防护窗格中，点击配置。

    5. 点击启用切换开关，然后点击保存。

    启用 reCAPTCHA SMS defense 后，系统还会启用账号卫士（如果尚未启用）。

    启用 reCAPTCHA SMS defense 的操作可能需要几分钟才能传播到我们的系统。传播完成后，您将在评估过程中开始接收与 reCAPTCHA SMS defense 相关的响应。

  4. 如需为 Firebase Authentication 或 Identity Platform 项目配置 reCAPTCHA SMS defense 设置，请执行以下操作：

    1. 在以下网址中，替换 PROJECT_ID、Recaptcha_MODE 和 START_SCORE：

      https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"emailPasswordEnforcementState":"OFF","phoneEnforcementState":"Recaptcha_MODE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}

      • PROJECT_ID：已启用 Identity Platform 的项目标识符。

      • Recaptcha_MODE：您要为 reCAPTCHA 手机号码身份验证强制执行设置的模式。有效值为 OFF、AUDIT 和 ENFORCE。如需启用 reCAPTCHA SMS defense，此参数必须设置为 AUDIT 或 ENFORCE，并且 useSmsTollFraudProtection 必须设置为 true。

        首次启用 reCAPTCHA SMS defense 时，请使用 AUDIT 模式，确保 reCAPTCHA SMS defense 设置正常运行。AUDIT 模式仅用于验证目的。此模式不会阻止未经授权的短信流量。验证指标信息中心内是否未显示任何失败。验证完成后，立即启用 ENFORCE 模式。如需详细了解这些模式的运作方式，请参阅 reCAPTCHA 手机号码身份验证强制执行模式

      • START_SCORE：请求在失败之前可以获得的最高付费欺诈评估得分。您可以将此得分设置为介于 0.1 和 0.9 之间。我们建议您先设置较高的阈值（例如 0.8），然后逐步降低得分。高于您设置的阈值的得分会被视为短信欺诈。将得分设置为 1.0 会停用欺诈防护功能，而将得分设置为 0.0 会屏蔽所有短信。 您设置的分数越低，规则就越严格。 例如，如果您将阈值设置为 0.3，则 reCAPTCHA 会使得分为 0.4 或更高的任何请求失败。

    2. 在已登录 Google Cloud 控制台的新浏览器窗口中输入网址。

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

      reCAPTCHA 密钥配置可能需要几分钟才能完成。

    2. 验证配置：

      • 获取 reCAPTCHA 配置详情：

        将 {replace-your-project} 替换为 projectId 或 projectNumber。 在侧边栏中执行 GetConfig API 以获取 reCAPTCHA 配置。

      • 验证 reCAPTCHA 短信防护功能是否已正确配置：

        1. 如果 reCAPTCHA 配置设置正确，则响应必须包含以下字段并具有指定值：

          • recaptchaKeys：字段不得为空，且已针对以下至少一个平台进行配置：iOS、Web 或 Android。
          • useSmsTollFraudProtection：此字段的值必须设置为 true。
          • phoneEnforcementState：该值必须设置为 ENFORCE 或 AUDIT。
          • tollFraudManagedRules：在此字段中，需要使用您选择的阈值配置 startScore，该阈值必须是介于 0 到 0.9 之间的值。

          否则，请重新配置 reCAPTCHA SMS defense。

          示例响应

            {
    "recaptchaConfig": {
        "recaptchaKeys": [
          {
            "key": "projects/{your-project}/keys/{recaptcha-key}",
            "type": "WEB"
          },
          {
            "type": "IOS"
          },
          {
            "type": "ANDROID"
          }
        ],
        "phoneEnforcementState": "ENFORCE",
        "tollFraudManagedRules": [
          {
            "startScore": 0.8,
            "action": "BLOCK"
          }
        ],
        "useSmsTollFraudProtection": true
    }
  }
  ```

    3. 确保 SDK 版本正确无误。

      Web

      更新到最新版本的 Web SDK。

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

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

      Android

      1. 更新到最新版本的 Android SDK。Android SDK 版本 23.1.0 及更高版本支持在 Android 应用中通过电子邮件地址和密码进行身份验证以及通过手机进行身份验证时使用 reCAPTCHA。

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

        将 Android SDK 与应用集成后，该 SDK 会自动提取 reCAPTCHA 配置，并强制执行您为已配置的提供方设置的阈值。

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

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

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

      iOS

      1. 更新到 iOS SDK 版本 11.6.0 或更高版本。

      将 iOS SDK 与应用集成后，该 SDK 会自动提取 reCAPTCHA 配置，并强制执行您为已配置的提供方设置的阈值。

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

      2. 如需验证链接器标志中是否列有 -ObjC，请依次前往目标 > 构建设置 > 所有 > 链接，然后验证 Other Linker Flags 是否显示 -ObjC。

    监控 reCAPTCHA SMS defense 的 reCAPTCHA 指标

    监控项目发出的 reCAPTCHA 指标，以验证基于短信的身份验证流程是否受到保护。例如，这些指标可帮助您确定是否已正确设置 Identity Platform 与 reCAPTCHA Enterprise API 的集成。它们还可以帮助您优化用户流量的得分阈值。

    通过检查项目向 Cloud Monitoring 发出的以下指标，验证 reCAPTCHA SMS defense 功能是否正常运行：

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

    强制执行 reCAPTCHA SMS defense

    在验证您的应用接收的用户流量是否可接受后，启用 reCAPTCHA ENFORCE 模式以主动阻止欺诈性请求，从而帮助保护用户。

    如需为项目或租户启用基于短信的身份验证流程的 ENFORCE 模式，请使用 Google APIs Explorer 在新的浏览器窗口中输入以下 HTTP 网址来更新项目配置，您需要在该窗口中登录 Google Cloud 控制台：

       https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"ENFORCE","useSmsTollFraudProtection":"true"}}}

    将 PROJECT_ID 替换为项目 ID。

    将 reCAPTCHA SMS defense 与机器人防护功能搭配使用

    您可以同时使用 reCAPTCHA SMS defense 和机器人防护功能。对于同时使用这两种保护功能的配置，请考虑以下事项：

    • 当您将手机身份验证强制执行状态设置为 AUDIT 时，如果请求满足至少一项评估，Identity Platform 就会通过该请求。我们建议您监控 reCAPTCHA 指标，以验证 reCAPTCHA 短信防御和机器人防护是否配置了合理的得分设置。
    • 当您将手机身份验证强制执行状态设置为 ENFORCE 时，Identity Platform 仅在请求同时满足这两项评估条件时才会通过该请求，并且请求失败会关闭，而不会回退到其他验证方法。

    如需同时启用这两项功能，请使用 Google APIs Explorer 更新项目配置：

            recaptchaConfig: {
          phoneEnforcementState:  'ENFORCE_MODE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

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

    在启用机器人防护功能的情况下停用 reCAPTCHA SMS defense

    如果您同时使用 reCAPTCHA SMS defense 和机器人防护功能，并且想要停用 reCAPTCHA SMS defense 但不停用机器人防护功能，请使用 Google APIs Explorer 更新项目配置：

        recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

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

    停用 reCAPTCHA SMS defense

    如需停用 reCAPTCHA 短信防御功能，请使用 Google APIs Explorer 更新项目配置，方法是在您登录 Google Cloud 控制台的新浏览器窗口中输入以下 HTTP 网址：

    
   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":"false"}}}

    将 PROJECT_ID 替换为项目 ID。

    如需在启用机器人防护功能的同时停用 reCAPTCHA SMS defense，请参阅在启用机器人防护功能的同时停用 reCAPTCHA SMS defense。

    后续步骤