Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

为基于短信的身份验证启用 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 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

如果初始的 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 SMS Defense 进行应用验证。如果用户请求通过了话费欺诈评估，系统会发送短信验证码。如果用户请求未通过话费欺诈评估，Identity Platform 会阻止该请求，并且不会发送包含验证码的短信。

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

准备工作

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

根据需要为您的应用或网站配置以下内容：
- 为用户启用手机登录功能。
- 为 Web、Android 或 iOS 应用添加多重身份验证。
根据需要为您的应用或网站配置 Firebase Authentication：
- 网站：设置手机验证
- iOS：手机身份验证设置
- Android：手机身份验证设置

启用 reCAPTCHA SMS defense

设置身份验证：

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

激活 Cloud Shell

创建服务身份：

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

将 PROJECT_ID 替换为项目 ID。

将 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：项目账号编号

在您的项目中启用 reCAPTCHA Enterprise API。
为您的项目启用 reCAPTCHA SMS defense：
1. 在 Google Cloud 控制台中，前往 reCAPTCHA 页面。
  
  前往 reCAPTCHA
2. 验证项目名称是否显示在资源选择器中。
  
  如果您没有看到项目名称，请点击资源选择器，然后选择您的项目。
3. 点击设置。
4. 在 SMS Defense 窗格中，点击配置。
5. 点击启用切换开关，然后点击保存。
启用 reCAPTCHA SMS Defense 后，系统还会启用账号保护程序（如果尚未启用）。

启用 reCAPTCHA SMS defense 的操作可能需要几分钟时间才能传播到我们的系统。传播完成后，您将在评估过程中开始接收与 reCAPTCHA SMS defense 相关的响应。
如需为 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：一个可配置的阈值，用于确定 SMS 请求在被标记为并阻止为付费欺诈之前可达到的最高得分。
    
    最低阈值为 0.0。阈值上限为 0.9。如果请求的得分高于阈值，则会被视为欺诈性请求。例如，如果您将阈值设置为 0.3，reCAPTCHA 将会屏蔽欺诈分数为 0.4 或更高的任何请求。
    
    如需提高欺诈防护级别，请将阈值设置为较低的值。如需降低欺诈防护级别，请将阈值设置为较高的值。此设置将允许更多得分较高的请求通过。
    
    对于初始实现，我们建议先从较高的阈值（例如 0.8）开始，然后根据您的具体风险承受能力逐步降低阈值。
    
    我们不建议将阈值设置为 0.0 或 1.0。将阈值设置为 0.0 会屏蔽所有短信，而设置为 1.0 会完全停用欺诈防护功能，这可能会导致无法向高风险区域发送短信。
    
    注意：如果您想停用欺诈防护功能，请将 Recaptcha_MODE 设置为 OFF。
2. 在已登录 Google Cloud 控制台的新浏览器窗口中输入相应网址。
如果您在 Web 或 Android 上使用 Identity Platform，请通过 Firebase 控制台注册您的应用：
- 对于 Android，注册每个使用 Identity Platform 的 Android 软件包名称。
- 对于网站，请为使用 reCAPTCHA 的每个网域添加一个授权网域：
  1. 在 Google Cloud 控制台中，前往 Identity Platform 页面。
    
    前往 Identity Platform
  2. 依次前往设置 > 安全性。
  3. 点击添加网域。
  4. 输入域名，然后点击添加以保存该域名。
  reCAPTCHA 密钥配置可能需要几分钟才能完成。

验证配置：

获取 reCAPTCHA 配置详细信息：

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

验证 reCAPTCHA SMS Defense 功能是否已正确配置：

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

确保 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 ENFORCE 模式，主动阻止欺诈性请求，以帮助保护用户。

如需为项目或租户启用基于短信的身份验证流程的 ENFORCE 模式，请使用 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":"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 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 更新项目配置，方法是在您登录 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。

后续步骤

详细了解 reCAPTCHA SMS Defense 功能。