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

检测并防范网站上与账号相关的欺诈活动

Account Defense 可帮助您检测和防范网站上的欺诈性账号活动。Account Defense 会监控用户活动模式，并构建特定于网站的行为模型，以帮助您识别凭据滥用行为，并保护用户账号免受自动攻击。

Fraud Defense 可帮助您保护关键操作，例如登录和结账。不过，通过观察特定用户在一段时间内对网站的使用行为，可以检测到许多不易察觉的账号滥用行为。Account Defense 是 Fraud Defense 的一项功能，可为您的网站创建特定于网站的模型，以检测可疑行为趋势或活动变化，从而帮助识别这些细微的滥用行为。通过使用特定于网站的模型，Account Defense 可帮助您检测以下内容：

可疑活动
具有类似行为的账号
特定用户标记为可信的设备发出的请求

根据 Account Defense 的分析和特定于网站的模型，您可以执行以下操作：

限制或停用欺诈性账号。
防止账号盗用尝试。
减少成功的账号入侵。
仅向来自合法用户账号的请求授予访问权限。
减少用户从其可信设备登录时的阻碍。

准备工作

为 Account Defense 配置网页

Account Defense 需要全面了解账号活动，才能实现有效检测。如需开始向 Account Defense 提供与账号相关的活动，以及创建和改进网站专属模型，请执行以下操作：

启用横向遥测数据收集。
报告关键用户操作。
评估关键用户事件。
为用户事件添加注释，以调优网站专用模型。

启用横向遥测数据收集

Account Defense 需要全面了解用户操作，例如用户是否已登录或即将登录。如需让 Account Defense 被动收集横向遥测数据，请在用户工作流中所有网页的后台加载 reCAPTCHA JavaScript 脚本，并使用您创建的基于得分的网站密钥。

以下示例展示了如何在网页中加载 reCAPTCHA JavaScript 脚本。

    <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

报告关键用户操作

为了检测可疑活动模式并构建更好的网站典型活动模式模型，Account Defense 需要有关关键用户操作的信息。因此，请通过对这些关键用户操作调用 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() 调用的结果。评估会为您提供风险判定结果，您可以使用该结果来决定如何处理潜在的欺诈活动。您可以采取的一些措施包括：屏蔽可疑请求、对有风险的登录进行质询，以及调查相关账号。

账号保护程序要求您提供稳定的账号标识符，以便进行评估并将用户活动（例如登录请求、已登录请求和注册请求）归因于特定账号。这有助于 Account Defense 处理用户活动模式，从而为每个账号构建活动模型，以便更好地检测异常和滥用流量。

选择一个用户不经常更改的稳定账号标识符 accountId，并在 projects.assessments.create 方法中将其提供给评估。对于与同一用户相关的所有事件，此稳定账号标识符应具有相同的值。您可以提供以下内容作为账号标识符：

用户标识符

如果每个账号都可以与一个稳定的用户名、邮箱或手机号码唯一关联，则您可以将其用作 accountId。当您提供此类跨网站标识符（可在多个网站上重复使用的标识符）时，Fraud Defense 会使用这些信息，通过标记滥用账号标识符并利用与这些标识符相关的跨网站滥用模式知识，基于跨网站模型更好地保护您的用户账号。

或者，如果您有与每个账号唯一关联的内部用户 ID，则可以将其作为 accountId 提供。

经过哈希处理或加密

如果您没有与每个账号唯一关联的内部用户 ID，则可以将任何稳定标识符转换为不透明的网站专用账号标识符。Fraud Defense 账号保护程序仍需要此标识符来了解用户活动模式并检测异常行为，但不会与其他网站共享。

选择任意稳定的账号标识符，并使用加密或哈希处理技术将其转换为不透明格式，然后再发送到 Fraud Defense：

加密（推荐）：使用可生成稳定密文的确定性加密方法对账号标识符进行加密。如需查看详细说明，请参阅以确定性方式加密数据。如果您选择对称加密而非哈希处理，则无需保留用户标识符与相应不透明用户标识符之间的映射。解密 Fraud Defense 返回的不透明标识符，将其转换为用户标识符。
哈希处理：我们建议使用 SHA256-HMAC 方法对账号标识符进行哈希处理，并使用您选择的自定义盐。由于哈希是单向的，因此您需要保留生成的哈希与用户标识符之间的映射，以便将返回的哈希账号标识符映射回原始账号。

除了为所有与账号相关的请求提供稳定的账号标识符之外，您还可以为某些特定请求提供可能不稳定的其他账号标识符。除了 accountId 之外，还提供特定于上下文的账号标识符，可帮助 Account Defense 更好地分析用户活动并检测账号接管尝试，从而确保用户账号安全。当您提供其他标识符时，Google Cloud Fraud Defense 会使用这些信息，通过标记滥用账号标识符并利用与这些标识符相关的跨网站滥用模式知识，基于跨网站模型改进对用户账号的保护。例如，您可以提供以下内容：

用作登录请求的登录句柄的用户名、邮箱或手机号码
已针对多重身份验证请求进行验证的邮箱或手机号码
用户在账号更新请求期间提供的邮箱或手机号码（主要或次要）
用户在注册请求期间提供的邮箱和手机号码

对于所有与账号相关的请求，请将所选的稳定账号标识符附加到 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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"]
  }
}

注意：如果您已在使用旧版 hashedAccountId 参数向 projects.assessments.create 方法提供稳定的账号标识符，则可以继续这样做。不过，由于 hashedAccountId 已弃用，新的集成应改用 accountId 参数。

代码示例

Java

如需向 Fraud Defense 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AccountDefenderAssessment.AccountDefenderLabel;
import com.google.recaptchaenterprise.v1.Assessment;
import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
import com.google.recaptchaenterprise.v1.Event;
import com.google.recaptchaenterprise.v1.ProjectName;
import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
import com.google.recaptchaenterprise.v1.TokenProperties;
import com.google.recaptchaenterprise.v1.UserId;
import com.google.recaptchaenterprise.v1.UserInfo;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AccountDefenderAssessment {

  public static void main(String[] args)
      throws IOException, NoSuchAlgorithmException, InvalidKeyException {
    // TODO(developer): Replace these variables before running the sample.
    // projectId: Google Cloud Project ID
    String projectId = "project-id";

    // recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha
    // services.
    String recaptchaSiteKey = "recaptcha-site-key";

    // token: The token obtained from the client on passing the recaptchaSiteKey.
    // To get the token, integrate the recaptchaSiteKey with frontend. See,
    // https://cloud.google.com/recaptcha-enterprise/docs/instrument-web-pages#frontend_integration_score
    String token = "recaptcha-token";

    // recaptchaAction: The action name corresponding to the token.
    String recaptchaAction = "recaptcha-action";

    // Unique ID of the user, such as email, customer ID, etc.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    // User phone number
    String phoneNumber = "555-987-XXXX";

    // User email address
    String emailAddress = "john.doe@example.com";

    accountDefenderAssessment(projectId, recaptchaSiteKey, token, recaptchaAction, accountId, phoneNumber, emailAddress);
  }

  /**
   * This assessment detects account takeovers. See,
   * https://cloud.google.com/recaptcha-enterprise/docs/account-takeovers The input is the hashed
   * account id. Result tells if the action represents an account takeover. You can optionally
   * trigger a Multi-Factor Authentication based on the result.
   */
  public static void accountDefenderAssessment(
      String projectId,
      String recaptchaSiteKey,
      String token,
      String recaptchaAction,
      String accountId,
      String phoneNumber,
      String emailAddress)
      throws IOException {
    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

      // Set the properties of the event to be tracked.
      Event.Builder eventBuilder =
          Event.newBuilder()
              .setSiteKey(recaptchaSiteKey)
              .setToken(token);

      // Set the account id, email address and phone number (of the user).
      eventBuilder.setUserInfo(
        UserInfo.newBuilder()
          .setAccountId(accountId)
          .addUserIds(UserId.newBuilder().setEmail(emailAddress))
          .addUserIds(UserId.newBuilder().setPhoneNumber(phoneNumber)));

      Event event = eventBuilder.build();

      // Build the assessment request.
      CreateAssessmentRequest createAssessmentRequest =
          CreateAssessmentRequest.newBuilder()
              .setParent(ProjectName.of(projectId).toString())
              .setAssessment(Assessment.newBuilder().setEvent(event).build())
              .build();

      Assessment response = client.createAssessment(createAssessmentRequest);

      // Check integrity of the response token.
      if (!checkTokenIntegrity(response.getTokenProperties(), recaptchaAction)) {
        return;
      }

      // Get the reason(s) and the reCAPTCHA risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }
      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));

      // Get the Account Defender result.
      com.google.recaptchaenterprise.v1.AccountDefenderAssessment accountDefenderAssessment =
          response.getAccountDefenderAssessment();
      System.out.println(accountDefenderAssessment);

      // Get Account Defender label.
      List<AccountDefenderLabel> defenderResult =
          response.getAccountDefenderAssessment().getLabelsList();
      // Based on the result, can you choose next steps.
      // If the 'defenderResult' field is empty, it indicates that Account Defender did not have
      // anything to add to the score.
      // Few result labels: ACCOUNT_DEFENDER_LABEL_UNSPECIFIED, PROFILE_MATCH,
      // SUSPICIOUS_LOGIN_ACTIVITY, SUSPICIOUS_ACCOUNT_CREATION, RELATED_ACCOUNTS_NUMBER_HIGH.
      // For more information on interpreting the assessment, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/account-defender#interpret-assessment-details
      System.out.println("Account Defender Assessment Result: " + defenderResult);
    }
  }

  private static boolean checkTokenIntegrity(
      TokenProperties tokenProperties, String recaptchaAction) {
    // Check if the token is valid.
    if (!tokenProperties.getValid()) {
      System.out.println(
          "The Account Defender Assessment call failed because the token was: "
              + tokenProperties.getInvalidReason().name());
      return false;
    }

    // Check if the expected action was executed.
    if (!tokenProperties.getAction().equals(recaptchaAction)) {
      System.out.printf(
          "The action attribute in the reCAPTCHA tag '%s' does not match "
              + "the action '%s' you are expecting to score",
          tokenProperties.getAction(), recaptchaAction);
      return false;
    }
    return true;
  }
}

解读关键用户事件的风险判定结果

当您在启用 Account Defense 的情况下创建评估时，Account Defense 会将 accountDefenderAssessment 作为评估响应的一部分返回。accountDefenderAssessment 的值可帮助您评估用户活动是合法的，还是欺诈活动。它还会返回一个评估 ID，您在为用户事件添加注释时需要使用该 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`	表示用户的属性与之前为此特定用户看到的属性相匹配。此值表示该用户使用的是之前曾用于访问您网站的可信设备。仅在以下情况下才会返回 `PROFILE_MATCH`：您可以使用多重身份验证 (MFA) 或双重身份验证 (2FA)，Account Defense 会在用户通过 MFA 或 2FA 验证后将用户个人资料标记为可信。您将评估注解为 `LEGITIMATE` 或 `PASSED_TWO_FACTOR`，并且 Account Defense 会将相应的用户个人资料标记为可信。
`RELATED_ACCOUNTS_NUMBER_HIGH`	表示该请求具有大量相关账号。这不一定意味着账号存在问题，但可能需要进一步调查。

注意：如果 accountDefenderAssessment 字段为空，则表示 Account Defense 没有任何要添加到得分的内容。

为事件添加注释，以调整特定于网站的模型

如需向 Account Defense 提供更多信息并改进网站专属检测模型，您必须通过创建评估来为评估的事件添加注释。

您可以通过向 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 可用时提供该 ID。	{ "accountId": "`ACCOUNT_ID`" }

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 可用时提供该 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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) 和一个空响应。

代码示例

Java

如需向 Fraud Defense 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Annotation;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Reason;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentResponse;
import com.google.recaptchaenterprise.v1.AssessmentName;
import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.util.UUID;

public class AnnotateAccountDefenderAssessment {

  public static void main(String[] args) throws IOException, NoSuchAlgorithmException {
    // TODO(developer): Replace these variables before running the sample.
    // projectID: GCloud Project id.
    String projectID = "project-id";

    // assessmentId: Value of the 'name' field returned from the CreateAssessment call.
    String assessmentId = "account-defender-assessment-id";

    // accountId: Set the accountId corresponding to the assessment id.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    annotateAssessment(projectID, assessmentId, accountId);
  }

  /**
   * Pre-requisite: Create an assessment before annotating. Annotate an assessment to provide
   * feedback on the correctness of recaptcha prediction.
   */
  public static void annotateAssessment(
      String projectID, String assessmentId, String accountId) throws IOException {

    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {
      // Build the annotation request.
      // For more info on when/how to annotate, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/annotate-assessment#when_to_annotate
      AnnotateAssessmentRequest annotateAssessmentRequest =
          AnnotateAssessmentRequest.newBuilder()
              .setName(AssessmentName.of(projectID, assessmentId).toString())
              .setAnnotation(Annotation.LEGITIMATE)
              .addReasons(Reason.PASSED_TWO_FACTOR)
              .setAccountId(accountId)
              .build();

      // Empty response is sent back.
      AnnotateAssessmentResponse response = client.annotateAssessment(annotateAssessmentRequest);
      System.out.println("Annotated response sent successfully ! " + response);
    }
  }
}

使用和解读账号入侵风险评分

账号入侵 (ATO) 风险评分功能可为 Account Defense 评估添加数字风险评分和人类可读的说明。这些数据分析可帮助您了解评估结果，并为后续行动或决策提供依据。

获取风险评分

如需接收风险评分和可解释性原因，请发送 CreateAssessment 请求，并在请求中添加 event.userInfo.accountId。

阅读风险评分和详情

风险评分和可解释性原因位于评估响应中的 accountDefenderAssessment.accountTakeoverVerdict 对象中。

风险评分： accountDefenderAssessment.accountTakeoverVerdict.risk
风险原因： accountDefenderAssessment.accountTakeoverVerdict.riskReasons
信任原因： accountDefenderAssessment.accountTakeoverVerdict.trustReasons

以下代码段展示了评估响应中的字段示例：

  "accountDefenderAssessment": {
    "labels": ["PROFILE_MATCH"],
    "accountTakeoverVerdict": {
      "risk": 0.249,
      "riskReasons": [{"reason": "CLIENT_ACCESSED_MANY_ACCOUNTS"}],
      "trustReasons": [{"reason": "PROFILE_MATCH"}, {"reason": "ACCOUNT_HISTORY_REPUTABLE"}]
    }
  }

解读 ATO 风险评分

使用风险评分时，请设定一个阈值，以确定何时采取保护措施。

使用 ATO 风险评分作为 SUSPICIOUS_LOGIN_ACTIVITY 标签的替代方案。请勿同时使用风险评分和标签来触发对同一评估的违规处置。您可以根据风险评分是否超过阈值或标签是否存在来配置违规处置逻辑。一般来说，风险评分可提供更精细的评估。

我们建议您先在平台流量上使用适当的阈值评估风险评分的效果，然后再将其用于违规处置。

如需根据风险评分采取行动，请在后端实现检查，如以下代码段所示：

if (assessment.accountDefenderAssessment.accountTakeoverVerdict.risk > YOUR_CHOSEN_THRESHOLD) {
  // Treat as suspicious
  // Implement protective actions
}

标准风险评分阈值

下表提供了标准风险评分阈值及其预期假正例率 (FPR)。根据可接受的 FPR 选择阈值。性能可能会有所不同，因此您可能需要根据观察到的性能调整阈值。

风险容忍度	建议的阈值	假正例率上限
低	0.5	4%
中	0.7	1%
高	0.9	0.25%

解读可解释性原因

可解释性原因可让您深入了解影响风险评分的因素。根据这些原因来优化您的决策。

风险原因：表示与账号入侵风险较高相关的因素。
信任原因：表明合法性的因素。

对于任何给定的风险评分，都可能同时出现风险原因和信任原因。

原因	类型	解读
`PROFILE_MATCH`	信任	该请求与此账号关联的受信任个人资料相匹配。这相当于 `AccountDefenderLabel.PROFILE_MATCH` 标签。
`ACCOUNT_HISTORY_REPUTABLE`	信任	账号的历史活动信誉良好。该账号过去不太可能遭到过入侵。
`CLIENT_HISTORICAL_BOT_ACTIVITY`	风险	过去曾观察到该客户端向此网站发送类似机器人的流量。此原因结合了历史声誉，表明已知客户端使用漫游器，即使当前请求是由人工发出的。
`ACCOUNT_IN_LARGE_RELATED_GROUP`	风险	该账号属于一个大型相关账号群组，这表明它可能是欺诈网络的一部分。系统会根据流量模式和请求特征的相似性来识别相关账号。
`CLIENT_ACCESSED_MANY_ACCOUNTS`	风险	观察到客户端在此网站上访问了多个账号。
`DISPOSABLE_EMAIL_DOMAIN`	风险	提供的邮箱属于已知或疑似提供临时、一次性邮箱网域的提供商。

调整账号入侵风险阈值

在评估账号入侵风险评分对流量的效果后，您可能需要调整阈值，以达到可接受的假正例率 (FPR) 和召回率。您可以根据观察到的性能调整阈值，也可以计算中间值以定位到特定的 FPR。

调整起付金额

如果观察到的 FPR 过高，请提高阈值。如果观察到的召回率过低，并且您可以容忍更高的 FPR，请降低阈值。

计算中间值

如需估算标准值之间的阈值的 FPR，请使用线性插值。以下示例展示了如何计算阈值为 0.85 时的 FPR：

FPR(T: 0.85) = (FPR(T: 0.8) + FPR(T: 0.9)) / 2 = (0.5% + 0.25%) / 2 = 0.375%

如需查找特定 FPR 的阈值，请在标准值之间进行插值。以下示例展示了如何查找 FPR 为 5% 时的阈值：

Threshold = 0.4 + (0.5 − 0.4) × (8% − 5%) / (8% − 4%)
Threshold = 0.4 + 0.1 × (3 / 4)
Threshold = 0.4 + 0.075 = 0.475

阈值为 0.475 时，预计会产生 5% 的 FPR。

后续步骤

使用 API 识别展现出相关行为的账号。

检测并防范网站上与账号相关的欺诈活动 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

为 Account Defense 配置网页

启用横向遥测数据收集

报告关键用户操作

评估关键用户事件

用户标识符

经过哈希处理或加密

curl

PowerShell

代码示例

Java

解读关键用户事件的风险判定结果

为事件添加注释，以调整特定于网站的模型

curl

PowerShell

代码示例

Java

使用和解读账号入侵风险评分

获取风险评分

阅读风险评分和详情

解读 ATO 风险评分

标准风险评分阈值

解读可解释性原因

调整账号入侵风险阈值

调整起付金额

计算中间值

后续步骤

检测并防范网站上与账号相关的欺诈活动