本文档介绍了如何使用 reCAPTCHA Enterprise 帐号卫士检测和防止网站上与帐号相关的欺诈活动。
reCAPTCHA Enterprise 可以帮助您保护登录和结账等关键操作。但是,通过在一段时间内观察特定用户在网站上的行为,可以检测到许多细微的帐号滥用行为。reCAPTCHA Enterprise 账号卫士为您的网站创建专门针对特定网站的模型,以检测可疑行为的趋势和活动变化,从而帮助识别此类细微的滥用行为。通过使用网站级模型,reCAPTCHA Enterprise 账号卫士可帮助您检测以下内容:
- 可疑活动
- 具有类似行为的账号
- 来自已针对特定用户标记为受信任的设备的请求
根据对 reCAPTCHA Enterprise 账号卫士和网站特定模型的分析,您可以执行以下操作:
- 限制或停用欺诈性帐号。
- 防止账号盗用尝试。
- 减少成功的帐号盗用。
- 请仅向来自合法用户账号的请求授予访问权限。
- 减少用户从可信设备登录的障碍。
准备工作
为 reCAPTCHA Enterprise 账号卫士配置网页
reCAPTCHA Enterprise 帐号卫士需要全面了解帐号活动,才能进行有效检测。如需开始将与帐号相关的活动提供给 reCAPTCHA Enterprise 帐号卫士,以及创建和改进网站特定模型,请执行以下操作:
启用水平遥测数据收集
reCAPTCHA Enterprise 账号卫士需要全面了解用户操作,例如用户是否已登录或引导登录。如需允许 reCAPTCHA Enterprise 帐号卫士被动收集横向遥测数据,请使用您在用户工作流中所有网页的后台创建且基于得分的网站密钥加载 reCAPTCHA Enterprise JavaScript 脚本。
以下示例展示了如何在网页中加载 reCAPTCHA Enterprise JavaScript 脚本。
<head> <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script> .... </head>
报告关键用户操作
为了检测可疑活动模式并更好地了解您网站上的典型活动模式,reCAPTCHA Enterprise 账号卫士需要有关关键用户操作的信息。因此,您可以通过针对网页上的关键用户操作调用 grecaptcha.enterprise.execute(),来报告这些关键用户操作。
我们建议您报告所有关键用户操作,因为这有助于收集其他信号。对于您要报告的每项用户操作,请将 grecaptcha.enterprise.execute()
的 action
参数的值替换为描述用户操作的操作名称。
下表列出了在报告关键用户操作时可以使用的操作名称。
操作名称 | 用户发起的事件或用户操作 |
---|---|
LOGIN |
登录网站。 |
REGISTRATION |
在网站上注册。 |
SECURITY_QUESTION_CHANGE |
请求更改安全问题。 |
PASSWORD_RESET |
请求重置密码。 |
PHONE_NUMBER_UPDATE |
请求更新手机号码。 |
EMAIL_UPDATE |
请求更新电子邮件地址。 |
ACCOUNT_UPDATE |
请求更新账号相关信息,例如详细联系信息。 |
TRIGGER_MFA |
触发 MFA 质询的操作。 |
REDEEM_CODE |
请求兑换代码。 |
LIST_PAYMENT_METHODS |
获取付款方式列表。 |
以下示例展示了如何在更新手机号码时调用 grecaptcha.enterprise.execute()
:
<script> function onClick(e) { e.preventDefault(); grecaptcha.enterprise.ready(async () => { const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'}); }); } </script>
评估关键用户事件
当您对用户操作调用 grecaptcha.enterprise.execute()
时,它会生成一个令牌。对于关键用户事件(例如登录成功和失败、注册以及已登录用户执行的操作),请创建评估以评估 grecaptcha.enterprise.execute()
调用的结果。评估会为您提供风险判定结果,让您可以决定如何处理潜在的欺诈性活动。您可以采取的一些措施包括拦截可疑请求、对存在风险的登录施加挑战以及调查感兴趣的帐号。
reCAPTCHA Enterprise 账号卫士要求您提供稳定的账号标识符,以便将用户活动(例如登录请求、登录请求和注册请求)归因于特定账号。这有助于 reCAPTCHA Enterprise 账号卫士了解用户活动模式,并为每个账号构建活动模型,以便更好地检测异常流量和滥用流量。
选择不常由用户更改的稳定帐号标识符 accountId
,并通过
projects.assessments.create
方法将其提供给评估。对于与同一用户相关的所有事件,这个稳定的帐号标识符应具有相同的值。您可以提供以下内容作为帐号标识符:
用户标识符
如果每个帐号都可以与稳定的用户名、电子邮件地址或手机号码唯一关联,您可以将其用作 accountId
。在您提供此类跨网站标识符(可跨网站重复使用的标识符)后,reCAPTCHA Enterprise 会使用这些信息,根据跨网站模型,标记存在滥用行为的帐号标识符,并掌握与这些标识符相关的跨网站滥用模式信息,从而提升对用户帐号的保护力度。
或者,如果您有一个与每个帐号唯一关联的内部用户 ID,则可以将其作为 accountId
提供。
经过哈希处理或加密
如果您没有与每个帐号唯一关联的内部用户 ID,则可以将任何稳定的标识符转换为不透明的网站专用帐号标识符。reCAPTCHA Enterprise 账号卫士仍然需要此标识符,才能了解用户活动模式并检测异常行为,但此标识符不会与其他网站共享。
选择任意稳定的账号标识符并将其设为不透明,然后使用加密或哈希处理方法将其发送到 reCAPTCHA Enterprise:
加密(推荐):使用可生成稳定密文的确定性加密方法对帐号标识符进行加密。如需了解详细说明,请参阅确定性地加密数据。当您选择对称加密而非哈希时,无需保留用户标识符与相应不透明用户标识符之间的映射。解密 reCAPTCHA Enterprise 返回的不透明标识符,以将其转换为用户标识符。
哈希处理:建议您使用 SHA256-HMAC 方法和您选择的自定义盐对帐号标识符进行哈希处理。由于哈希是单向的,因此您需要在生成的哈希与用户标识符之间保持映射,以便将返回且经过哈希处理的帐号标识符映射回原始帐号。
除了为所有与帐号相关的请求提供稳定的帐号标识符之外,您还可以针对某些特定请求提供额外的帐号标识符(可能不稳定)。除了 accountId
之外,还提供特定上下文的账号标识符,有助于 reCAPTCHA Enterprise 账号卫士更好地了解用户活动并检测账号盗用尝试,以确保您的用户账号安全。当您提供额外的标识符后,reCAPTCHA Enterprise 会使用这些信息,根据跨网站模型来标记存在滥用行为的帐号标识符,并运用与这些标识符相关的跨网站滥用模式信息,来提升对用户帐号的保护力度。例如,您可以提供以下内容:
用作登录请求登录句柄的用户名、电子邮件地址或手机号码
针对多重身份验证请求通过验证的电子邮件地址或手机号码
用户在请求账号更新时提供的电子邮件地址或手机号码(主要或辅助)
用户在注册请求期间提供的电子邮件地址和手机号码
对于所有与帐号相关的请求,将选择的固定帐号标识符附加到
projects.assessments.create
方法中的 accountId
参数。(可选)在评估中使用 userIds
字段,为相关请求提供其他帐号标识符。
在使用任何请求数据之前,请先进行以下替换:
- PROJECT_ID:您的 Google Cloud 项目 ID
- TOKEN:从
grecaptcha.enterprise.execute()
调用返回的令牌 - KEY_ID:与网站关联的 reCAPTCHA 密钥
- ACCOUNT_ID:与您网站用户账号的用户账号唯一关联的标识符
- EMAIL_ADDRESS:可选。与此请求关联的电子邮件地址(如果有)
- PHONE_NUMBER:可选。与此请求关联的手机号码(如果有)
- USERNAME:可选。与此请求关联的用户名(如果有)
HTTP 方法和网址:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
请求 JSON 正文:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userInfo": { "accountId": "ACCOUNT_ID", "userIds": [ { "email": "EMAIL_ADDRESS" }, { "phoneNumber": "PHONE_NUMBER" }, { "username": "USERNAME" } ] } } }
如需发送请求,请选择以下方式之一:
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 响应:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY", "userInfo": { "accountId": "ACCOUNT_ID" } }, "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000", "accountDefenderAssessment": { "labels": ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
代码示例
Java
如需向 reCAPTCHA Enterprise 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
解读关键用户事件的风险判定
当您在启用了帐号卫士的情况下创建评估时,帐号卫士会在评估响应中返回 accountDefenderAssessment
。accountDefenderAssessment
的值可帮助您评估用户活动是合法的还是欺诈性的。它还会返回您在为用户事件添加注释时需要使用的评估 ID。
以下是一个 JSON 响应示例:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY_ID", "expectedAction": "USER_ACTION" }, "name": "projects/PROJECT_ID/assessments/b6ac310000000000X", "accountDefenderAssessment": { labels: ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
accountDefenderAssessment
字段可以是以下任何值:
值 | 说明 |
---|---|
SUSPICIOUS_LOGIN_ACTIVITY |
表示相应请求存在凭据填充或帐号盗用的高风险。 |
SUSPICIOUS_ACCOUNT_CREATION |
表示相应请求代表存在滥用帐号创建行为的较高风险。 |
PROFILE_MATCH |
表示用户的属性与此特定用户之前查看过的属性匹配。该值表示,此用户使用的可信设备曾被用于访问您的网站。 仅在以下情况下会返回
|
RELATED_ACCOUNTS_NUMBER_HIGH |
表示请求包含大量相关帐号。这并不一定意味着帐号有问题,但可能需要进一步调查。 |
为事件添加注解,以调整网站特定模型
如需向 reCAPTCHA Enterprise 账号卫士提供更多信息并改进您的网站特有检测模型,您必须通过创建评估来为已评估的事件添加注释。
您可以向 projects.assessments.annotate
方法发送请求(其中包含评估 ID),从而为评估添加注释。在该请求的正文中,您可以添加标签,用于提供与评估中描述的事件相关的更多信息。
如需为评估添加注解,请执行以下操作:
-
根据您的用例确定要在请求 JSON 正文中添加的信息和标签。
下表列出了可用于为事件添加注释的标签和值:
标签 说明 请求示例 reasons
必需。支持评估的标签。 在事件发生后的几秒钟或几分钟内,在
reasons
标签中提供实时事件详情,因为这些详情会影响实时检测。如需查看可能值的列表,请参阅原因值。
示例:如需检测帐号盗用,请使用
CORRECT_PASSWORD
或INCORRECT_PASSWORD
值注释输入的密码是否正确。如果您部署了自己的 MFA,则可以添加以下值:INITIATED_TWO_FACTOR
、PASSED_TWO_FACTOR
或FAILED_TWO_FACTOR
。{ "reasons": ["INCORRECT_PASSWORD"] }
annotation
可选。指示评估合法性的标签。 在“
annotation
”标签中提供有关登录和注册事件的信息,以验证或更正您的风险评估。可能的值:
LEGITIMATE
或FRAUDULENT
。您可以随时发送此信息,也可以将其作为批量作业的一部分发送。 不过,我们建议您在事件发生后几秒或几分钟内发送这些信息,因为它们会影响实时检测。
{ "annotation": "LEGITIMATE" }
accountId
可选。用于将帐号 ID 与事件相关联的标签。
如果您创建的评估没有帐号 ID,请使用此标签来提供事件的帐号 ID(如果可用)。
{ "accountId": "ACCOUNT_ID" }
使用适当的标签创建注解请求。
在使用任何请求数据之前,请先进行以下替换:
- ASSESSMENT_ID:从
projects.assessments.create
调用返回的name
字段的值。 - ANNOTATION:可选。指示评估结果是合法还是欺诈的标签。
- REASONS:可选。支持注解的原因。如需查看可能值的列表,请参阅原因值。
- ACCOUNT_ID:可选。与您网站上的用户帐号相关联的唯一标识符。
如需了解详情,请参阅注解标签。
HTTP 方法和网址:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
请求 JSON 正文:
{ "annotation": ANNOTATION, "reasons": REASONS, "accountId": ACCOUNT_ID }
如需发送请求,请选择以下方式之一:
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:从
代码示例
Java
如需向 reCAPTCHA Enterprise 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
启用 reCAPTCHA Enterprise 账号卫士
为 reCAPTCHA Enterprise 账号卫士配置网页后,您可以启用 reCAPTCHA Enterprise 账号卫士。
在 Google Cloud 控制台中,前往 reCAPTCHA Enterprise 页面。
验证项目名称是否显示在页面顶部的资源选择器中。
如果您没有看到项目的名称,请点击资源选择器,然后选择您的项目。
- 点击 设置。
在账号卫士窗格中,点击启用。
在配置帐号卫士对话框中,点击启用。
启用 reCAPTCHA Enterprise 账号卫士的操作可能需要几个小时才能传播到我们的系统。启用该功能的操作传播到我们的系统后,您将在评估过程中开始接收与账号卫士相关的响应。