本文档介绍如何使用 SMS Defense 检测并防止依赖短信进行双重身份验证 (2FA) 或手机验证的企业遭受短信注入攻击，因为这些企业是短信话费欺诈的潜在目标。
基于短信的身份验证（2FA 和登录）是登录和注册安全方面的业界标准，但它无法防范短信话费欺诈或短信注入欺诈。在您发送短信之前，SMS defense 会为您提供一个风险得分，该得分表示相应手机号码涉及短信话费欺诈的可能性。根据此得分，您可以在欺诈性短信发送给短信服务提供商之前允许或屏蔽这些短信。
SMS defense 风险得分与 reCAPTCHA 全局得分呈反比关系。SMS defense 风险得分 0.0 表示短信话费欺诈发生的可能性较低；风险得分 1.0 表示短信话费欺诈发生的可能性较高。 如需详细了解 reCAPTCHA 得分，请参阅 解读网站评估。 如果您使用的是 Firebase Authentication 或 Identity Platform，请参阅 Identity Platform 文档。
如需了解其他信息，请参阅 SMS defense 博客。
准备工作
根据您是 reCAPTCHA 的现有用户还是 reCAPTCHA 的新用户，按照相应标签页中的说明操作：
reCAPTCHA 现有用户
如果您是 reCAPTCHA 的现有用户，请在您的 Google Cloud 项目上启用 SMS defense：
在 Google Cloud 控制台中，前往 reCAPTCHA 页面。
验证项目名称是否显示在资源选择器中。
如果您没有看到项目名称，请点击资源选择器， 然后选择您的项目。
点击设置。
在 SMS defense 窗格中，点击配置 。
点击启用 开关，然后点击保存 。
启用 SMS defense 的操作可能需要几分钟时间才能传播到我们的系统。启用该功能的操作传播到我们的系统后，您将在评估过程中开始接收与 SMS defense 相关的响应。
reCAPTCHA 新用户
如果您是 reCAPTCHA 的新用户，请执行以下操作：
-
根据您要在网站还是移动应用中使用 SMS defense，按照以下步骤集成 reCAPTCHA：
网站
移动应用
- 为您的移动应用创建基于得分的密钥。
- 将 reCAPTCHA 与 iOS 应用或 Android 应用集成
- 在您的 Google Cloud 项目上启用
SMS defense：
在 Google Cloud 控制台中，前往 reCAPTCHA 页面。
验证项目名称是否显示在资源选择器中。
如果您没有看到项目名称，请点击资源选择器， 然后选择您的项目。
点击设置。
在 SMS defense 窗格中，点击配置 。
点击启用 开关，然后点击保存 。
启用 SMS defense 的操作可能需要几分钟时间才能传播到我们的系统。启用该功能的操作传播到我们的系统后，您将在评估过程中开始接收与 SMS defense 相关的响应。
使用手机号码创建评估
对于 SMS defense，请使用通过 execute() 函数生成的令牌和手机号码创建评估，方法是从后端使用 reCAPTCHA 客户端库或 REST API。
本文档介绍如何使用 REST API 创建评估。 如需了解如何使用客户端库创建评估， 请参阅创建评估。
在创建评估之前，请执行以下操作：
设置向 reCAPTCHA 进行的身份验证。
您选择的身份验证方法取决于设置 reCAPTCHA 的环境。下表可帮助您选择适当的身份验证方法和受支持的接口来设置身份验证：
环境 接口 身份验证方法 Google Cloud - REST
- 客户端库
使用关联的服务账号。 本地或其他云服务提供商 REST 使用 API 密钥 或 工作负载身份联合。 如果您想使用 API 密钥，建议您通过 应用 API 密钥限制来保护 API 密钥。
客户端库 使用以下资源：
- 对于 Python 或 Java，请使用 API 密钥或 工作负载身份联合。
如果您想使用 API 密钥，建议您通过 应用 API 密钥限制来保护 API 密钥。
- 对于其他语言，请使用工作负载身份联合。
选择一个稳定的账号标识符
accountId，该标识符不会经常被用户更改 ，并在projects.assessments.create方法中将其提供给评估。对于与同一用户相关的所有事件，此稳定账号标识符应具有相同的值。您可以提供以下内容作为账号标识符：用户标识符
如果每个账号都可以与稳定的用户名、电子邮件地址或手机 号码唯一关联，则可以使用它作为
accountId。当您提供此类跨网站标识符（可在多个网站中重复使用的标识符）时，reCAPTCHA 会使用此信息，通过标记滥用账号标识符并使用与这些标识符相关的跨网站滥用模式知识，根据跨网站模型改进对用户账号的保护。或者，如果您有一个与每个账号唯一关联的内部用户 ID，则可以 将其作为
accountId提供。经过哈希处理或已加密
如果您没有与每个账号唯一关联的内部用户 ID，则可以将 任何稳定标识符转换为不透明的网站专用账号标识符。reCAPTCHA 账号保护程序仍需要此标识符来了解用户活动 模式并检测异常行为，但它不会在其他网站之间共享。
选择任何稳定的账号标识符，并使用加密或哈希处理使其不透明，然后再发送给 reCAPTCHA：
加密（推荐）：使用生成稳定密文的确定性 加密方法对账号标识符进行加密。如需详细说明，请参阅 加密数据 确定性地。如果您选择对称加密而不是哈希处理，则无需保留用户标识符与相应不透明用户标识符之间的映射。解密 reCAPTCHA 返回的不透明标识符，将其转换为 用户标识符。
哈希处理：我们建议使用 SHA256-HMAC 方法和 您选择的自定义盐对账号标识符进行哈希处理。由于哈希处理是单向的，因此您需要保留生成的哈希值与用户标识符之间的映射 以便将返回的哈希账号标识符映射回原始账号。
添加 accountId 参数，并将 E.164 格式的手机号码作为
UserId 添加到
评估中进行验证，该评估位于 projects.assessments.create 方法中。
在使用任何请求数据之前， 请先进行以下替换：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- TOKEN：从
grecaptcha.enterprise.execute()调用返回的令牌。 - KEY_ID：您在网站上安装的基于得分的密钥。
- ACCOUNT_ID：您网站专有的用户账号标识符。
- PHONE_NUMBER：需要检查是否具有恶意性的手机号码。手机号码必须采用 E.164 格式，且不得经过哈希处理或加密。
HTTP 方法和网址：
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
请求 JSON 正文：
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userInfo": {
"accountId": "ACCOUNT_ID",
"userIds": [
{
"phoneNumber": "PHONE_NUMBER"
}
]
}
}
}
如需发送请求，请选择以下方式之一：
curl
将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"
PowerShell
将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
您应该收到类似以下内容的 JSON 响应：
{
"event": {
…
},
"name": "ASSESSMENT_ID",
"phoneFraudAssessment": {
"smsTollFraudVerdict": {
"risk": 0.3
}
}
}
您收到的响应在
phoneFraudAssessment.smsTollFraudVerdict
字段中包含risk得分。得分越高，手机号码的风险可能越大；得分越低，手机号码的合法性可能越高。
您应对根据评估结果采取的操作负责。
对于最简单的集成，您可以为 phoneFraudAssessment.smsTollFraudVerdict.risk 设置阈值，以帮助您做出决策。
给评估添加注释
为了跟踪短信流量并改进欺诈检测，您必须在发送短信后或手机号码成功验证后 10 分钟内给评估添加注释。
您可以通过向
projects.assessments.annotate
方法发送包含评估 ID 的请求来给评估添加注释。在该请求的正文中，在 phoneAuthenticationEvent 字段中添加 E.164 格式的手机号码。
如需为评估添加注解，请执行以下操作：
根据您的使用场景确定要在请求 JSON 正文中添加的信息和标签。
下表列出了可用于给事件添加注释的标签和值：
标签 说明 请求示例 reasons必需。用于支持评估的标签。
在事件发生后的几秒或几分钟内，在
reasons标签中提供实时事件详细信息，因为它们会影响实时检测。可能的值：
INITIATED_TWO_FACTOR：已通过 短信发送验证码。PASSED_TWO_FACTOR：验证码已成功验证。FAILED_TWO_FACTOR：验证码无效。
{ "reasons": ["INITIATED_TWO_FACTOR"], "phoneAuthenticationEvent": { "phoneNumber": "+18005550175" } }annotation可选。用于指示评估合法性的标签。
在
annotation标签中提供有关登录和 注册事件的事实，以验证或更正风险评估。可能的值：
LEGITIMATE或FRAUDULENT。我们建议在事件发生后的几秒或几分钟内发送此信息，因为它会影响实时检测。
{ "annotation": "LEGITIMATE" }使用适当的标签创建注解请求。
在使用任何请求数据之前， 请先进行以下替换：
- ASSESSMENT_ID：从
projects.assessments.create调用返回的name字段的值。 - ANNOTATION：可选。用于指示评估结果是合法还是欺诈的标签。
- REASONS：支持注解的原因。如需查看可能值的列表， 请参阅原因值。
- PHONE_NUMBER：接受评估的手机号码。手机号码必须采用 E.164 格式，且不得经过哈希处理或加密。
HTTP 方法和网址：
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
请求 JSON 正文：
{ "annotation": ANNOTATION, "reasons": REASONS, "phoneAuthenticationEvent": { "phoneNumber": "PHONE_NUMBER" } }如需发送请求，请选择以下方式之一：
curl
将请求正文保存在名为
request.json的文件中，然后执行以下命令：curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"PowerShell
将请求正文保存在名为
request.json的文件中，然后执行以下命令：$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand Content您应该会收到一个成功的状态代码 (2xx) 和一个空响应。
- ASSESSMENT_ID：从