为基于短信的身份验证启用 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 提供风险得分，以表明用户手机号码发生短信话费欺诈的可能性。然后，系统会将此得分与您配置的阈值进行比较。如果风险得分超过此阈值，系统将不会发送短信，从而有效阻止欺诈尝试。

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

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

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

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

审核模式

当您将手机身份验证强制执行设置为审核模式时，Identity Platform 会使用 reCAPTCHA SMS defense 进行应用验证。如果用户的请求通过了话费欺诈评估，系统会发送短信验证码。如果用户的请求未通过话费欺诈评估，并且您使用的是客户端 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

如果初始话费欺诈评估失败，审核模式会针对 Play Integrity API 验证您的应用。如果此验证失败，系统会触发 reCAPTCHA v2。 在以下情况下，系统可能会触发 reCAPTCHA v2：

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

iOS

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

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

强制执行模式

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

在强制执行模式下，无需进行后备验证，因此您无需为应用设置任何其他验证方法。不过，我们建议您为 Web 应用设置 reCAPTCHA 验证程序，以确保在您决定将应用的 reCAPTCHA 模式更改为 AUDIT 或 OFF时启用 reCAPTCHA v2。

准备工作

在为 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、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.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 控制台注册您的应用：

    • 对于 Android，请注册每个使用 Identity Platform的 Android 软件包名称。

    • 对于 Web，请为每个使用 reCAPTCHA 的网域添加授权网域：

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

        前往 Identity Platform

      2. 依次前往设置 > 安全。

      3. 点击添加网域 。

      4. 输入域名，然后点击添加 以保存该网域。

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

  6. 验证配置：

    • 提取 reCAPTCHA 配置详细信息：

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

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

      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
    }
  }
  ```

  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。reCAPTCHA 支持在 Android 应用中使用电子邮件和密码身份验证以及手机身份验证，此功能在 Android SDK 23.1.0 及 更高版本上可用。

      此外，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 是否列在链接器标志中，请依次前往 目标 > Build 设置 > 全部 > 链接 ，并验证 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 SMS Defense 和漫游器保护功能是否都配置了合理的得分设置。
  • 当您将手机身份验证强制执行状态设置为 ENFORCE 时，Identity Platform 仅在请求满足这两项评估并且请求失败关闭而不回退到其他验证方法时，才会传递该请求。

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

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

将 ENFORCE_MODE 替换为您要为 reCAPTCHA 手机身份验证强制执行设置的模式。有效值为 OFF、AUDIT 和 ENFORCE。 首次启用 reCAPTCHA SMS defense 时，我们建议您将此参数设置为 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 SMS defense，请使用 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":"OFF","useSmsTollFraudProtection":"false"}}}

将 PROJECT_ID 替换为项目 ID。

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

后续步骤