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

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

概览

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

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

然后，reCAPTCHA 会向 Firebase Authentication 或 Identity Platform 提供风险评分，该评分表示用户手机号码发生短信话费欺诈的可能性。然后，系统会将此分数与您配置的阈值进行比较。如果用户请求通过了话费欺诈评估，系统会发送短信验证码。如果风险评分超过您配置的阈值，Identity Platform 会屏蔽请求，并且不会发送包含验证码的短信。

启用 reCAPTCHA SMS defense 后，无需进行后备验证，您也无需为应用设置任何其他验证方法。不过，我们建议您为 Web 应用设置 reCAPTCHA 验证程序，以确保在您决定停用 reCAPTCHA SMS defense 时，reCAPTCHA v2 可用。

如需了解 reCAPTCHA SMS Defense 得分的工作原理，请参阅解读得分。

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

准备工作

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

启用 reCAPTCHA SMS defense

  1. 设置身份验证：

    1. 在 Google Cloud 控制台中，激活 Cloud Shell。

      激活 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 Defense窗格中，点击配置。

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

    启用 reCAPTCHA SMS defense 时，账号保护程序也会一并启用（如果尚未启用）。

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

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

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

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

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

      • START_SCORE：一个可配置的阈值，用于确定短信请求在被标记并屏蔽为话费欺诈之前可以达到的最高分数。

        最低阈值为 0.0。阈值上限为 0.9。 任何得分高于阈值的请求都会被视为欺诈。例如，如果您将阈值设置为 0.3，reCAPTCHA 将屏蔽欺诈分数达到 0.4 或更高的所有请求。

        如需提高欺诈防护级别，请将阈值设置为较低的值。如需降低欺诈防护级别，请将阈值设置为较高的值。此设置将允许更多得分较高的请求通过。

        对于初始实现，我们建议从较高的阈值（例如 0.8）开始，然后根据您的特定风险承受能力以迭代方式降低该阈值。

        我们不建议将阈值设置为 0.0 或 1.0。将阈值设置为 0.0 会屏蔽所有短信，而设置为 1.0 则会完全停用欺诈防护功能，这可能会导致无法向高风险区域发送短信。

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

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

  6. 验证配置：

    • 提取 reCAPTCHA 配置详情：

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

    • 验证 reCAPTCHA SMS defense 是否已正确配置：

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

        • recaptchaKeys：字段不得为空，且至少针对以下平台之一进行了配置：iOS、Web 或 Android。
        • useSmsTollFraudProtection：此字段的值必须设置为 true。
        • phoneEnforcementState：该值必须设为 ENFORCE。
        • 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
    }
  }
  ```

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

    Web

    更新到最新版本的 Web SDK。

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

    将 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 文件的 dependencies 部分：

      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 是否已列在链接器标志中，请依次前往 Target（目标）> Build Settings（构建设置）> All（全部）> Linking（链接），然后验证 Other Linker Flags 是否显示 -ObjC。

监控 reCAPTCHA SMS defense 的 reCAPTCHA 指标

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

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

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

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

您可以同时使用 reCAPTCHA SMS defense 和机器人防护。如果两者都已启用，并且 phoneEnforcementState 设置为 ENFORCE，则 Identity Platform 仅在请求满足这两项评估时才会通过，并且请求会故障关闭，而不会回退到其他验证方法。

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

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

在使用机器人防护功能时停用 reCAPTCHA SMS defense

如果您同时使用 reCAPTCHA SMS defense 和机器人防护功能，并且希望在不停用机器人防护功能的情况下停用 reCAPTCHA SMS defense，请使用 Google APIs Explorer 更新项目配置：

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

将 phoneEnforcementState 设置为 ENFORCE，并将 useSmsBotScore 设置为 true，以便为手机身份验证流程启用机器人防护。

停用 reCAPTCHA SMS defense

如需停用所有手机 reCAPTCHA 保护（包括 reCAPTCHA SMS Defense），请使用 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.phoneEnforcementState,recaptchaConfig.useSmsTollFraudProtection,recaptchaConfig.useSmsBotScore","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":false,"useSmsBotScore":false}}}

将 PROJECT_ID 替换为项目 ID。

如需在使用漫游器防护功能时停用 reCAPTCHA SMS defense，请参阅在使用漫游器防护功能时停用 reCAPTCHA SMS defense。

后续步骤