为基于短信的身份验证启用 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 之前,请完成以下任务:
根据需要为您的应用或网站配置以下内容:
根据需要为您的应用或网站配置 Firebase Authentication:
启用 reCAPTCHA SMS defense
设置身份验证:
-
在 Google Cloud 控制台中,激活 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. \ --role=roles/identitytoolkit.serviceAgent替换以下内容:
PROJECT_ID:项目 IDPROJECT_NUMBER:项目账号
-
在您的项目上启用 reCAPTCHA Enterprise API。
为您的项目启用 reCAPTCHA SMS defense:
在 Google Cloud 控制台中,前往 reCAPTCHA 页面。
验证项目名称是否显示在资源选择器中。
如果您没有看到项目名称,请点击资源选择器,然后选择您的项目。
点击 设置。
在SMS Defense窗格中,点击配置。
点击启用切换开关,然后点击保存。
启用 reCAPTCHA SMS defense 时,账号保护程序也会一并启用(如果尚未启用)。
启用 reCAPTCHA SMS defense 的操作可能需要几分钟才能传播到我们的系统。传播完成后,您将在评估过程中开始接收与 reCAPTCHA SMS defense 相关的响应。
如需为 Firebase Authentication 或 Identity Platform 项目配置 reCAPTCHA SMS Defense 设置,请执行以下操作:
在以下网址中,替换
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到1.0之间,以0.1为增量。 任何得分高于阈值的请求都会被视为欺诈。例如,如果您将阈值设置为0.3,reCAPTCHA 将屏蔽欺诈分数达到0.4或更高的所有请求。如需提高欺诈防护级别,请将阈值设置为较低的值。如需降低欺诈防护级别,请将阈值设置为较高的值。此设置将允许更多得分较高的请求通过。
对于初始实现,我们建议从
0.7或更低的阈值(例如0.5)开始,然后根据您的风险承受能力调整阈值。我们不建议将阈值设置为
0.0或0.7以上:- 阈值为
0.0会屏蔽所有短信。 - 阈值介于
0.8到1.0之间可能会导致无法向高风险区域发送短信。 - 阈值为
1.0时,会关闭基于分数的屏蔽。
- 阈值为
在已登录 Google Cloud 控制台的新浏览器窗口中输入该网址。
如果您在 Web 或 Android 上使用 Identity Platform,请通过 Firebase 控制台注册您的应用:
对于 Android,请注册每个使用 Identity Platform 的 Android 软件包名称。
对于 Web,请为每个使用 reCAPTCHA 的网域添加一个授权网域:
在 Google Cloud 控制台中,前往 Identity Platform 页面。
前往设置 > 安全。
点击添加网域。
输入域名,然后点击添加以保存该域名。
reCAPTCHA 密钥预配可能需要几分钟才能完成。
验证配置:
提取 reCAPTCHA 配置详情:
将
{replace-your-project}替换为您的projectId或projectNumber。 在侧边栏中执行GetConfigAPI 以提取 reCAPTCHA 配置。验证 reCAPTCHA SMS defense 是否已正确配置:
如果 reCAPTCHA 配置设置正确,则响应必须包含以下字段,且具有指定值:
recaptchaKeys:字段不得为空,且至少针对以下平台之一进行了配置:iOS、Web 或 Android。useSmsTollFraudProtection:此字段的值必须设置为true。phoneEnforcementState:该值必须设为ENFORCE。tollFraudManagedRules:在此字段中,必须将startScore设置为您选择的阈值。有效值介于0.0到1.0之间,以0.1为增量。如需允许通过所有受支持的运营商网络发送短信,请将startScore设置为0.1到0.7之间的值,例如0.5。
否则,请重新配置 reCAPTCHA SMS defense。
示例响应
{ "recaptchaConfig": { "recaptchaKeys": [ { "key": "projects/{your-project}/keys/{recaptcha-key}", "type": "WEB" }, { "type": "IOS" }, { "type": "ANDROID" } ], "phoneEnforcementState": "ENFORCE", "tollFraudManagedRules": [ { "startScore": 0.5, "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
更新到最新版 Android SDK。Android SDK 23.1.0 及更高版本支持在 Android 应用中通过 reCAPTCHA 进行邮箱和密码身份验证以及手机身份验证。
此外,reCAPTCHA 支持需要 API 级别 23 (Marshmallow) 或更高级别以及 Android 6 或更高版本。
将 Android SDK 与应用集成后,SDK 会自动提取 reCAPTCHA 配置,并为您配置的提供商强制执行您设置的阈值。
将以下 build 规则添加到应用级
build.gradle文件的 dependencies 部分:implementation 'com.google.android.recaptcha:recaptcha:18.5.1'请务必使用 reCAPTCHA SDK 18.5.1 或更高版本。
iOS
- 更新到 iOS SDK 11.6.0 或更高版本。
将 iOS SDK 与应用集成后,SDK 会自动提取 reCAPTCHA 配置,并强制执行您为已配置的提供方设置的阈值。
如需将 reCAPTCHA iOS SDK 集成到您的应用,请参阅准备 iOS 环境。
如需验证
-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 功能是否正常运行:
identitytoolkit.googleapis.com/recaptcha/verdict_countidentitytoolkit.googleapis.com/recaptcha/token_countidentitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores
如需了解详情,请参阅监控 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。
后续步骤
- 详细了解 reCAPTCHA SMS Defense 功能。