检测并防范移动应用中的与账号相关的欺诈活动

本文档介绍如何使用 reCAPTCHA 账号防御功能检测并防止移动应用上与账号相关的欺诈活动。

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

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

根据 reCAPTCHA 账号卫士的分析和特定于网站的模型，您可以采取以下措施：

限制或停用欺诈性账号。
防止账号盗用尝试。
减少成功盗用账号的情况。
仅向来自合法用户账号的请求授予访问权限。
减少用户通过可信设备登录时的摩擦。

准备工作

向项目添加结算账号以触发自动安全审核后，即可使用适用于移动应用的 reCAPTCHA 账号保护功能。向项目添加结算账号，以便将您的移动应用纳入此功能的使用范围。
为 reCAPTCHA 准备环境。
创建基于得分的密钥。

为 reCAPTCHA 账号防卫功能配置移动应用

reCAPTCHA 账号防御功能需要全面了解账号活动，才能有效检测。如需开始向 reCAPTCHA 账号卫士提供与账号相关的活动，并创建和改进特定于网站的模型，请执行以下操作：

将 reCAPTCHA 与移动应用集成。
- 对于 Android 应用，请参阅将 reCAPTCHA 与 Android 应用集成。
- 对于 iOS 应用，请参阅将 reCAPTCHA 与 iOS 应用集成。
报告关键用户操作。
评估关键用户事件。
通过注释用户事件来调整特定于您网站的模型。

报告关键用户操作

为了检测可疑活动模式并更好地构建您网站上的典型活动模式，reCAPTCHA 账号防御功能需要了解关键用户操作的相关信息。对于应用中受 reCAPTCHA 保护的每项操作，请使用 RecaptchaAction 调用 execute() 方法。如需详细了解 execute() 和 RecaptchaAction，请参阅以下内容：

Android：execute() 和 RecaptchaAction。
iOS：execute() 和 RecaptchaAction。

reCAPTCHA 提供了一组内置操作，如有必要，您还可以创建自定义操作。

下表列出了报告关键用户操作时可以使用的操作名称。

注意：操作名称无需限定为以下列表中的名称。您可以使用 custom() for Android 或 custom() for iOS 添加有意义且描述用户操作的操作名称，例如 PASSWORD_RESET 或 ACCOUNT_UPDATE。

操作名称	用户发起的事件或用户操作
`LOGIN`	登录移动应用。
`SIGNUP`	在移动应用中注册。

评估关键用户事件

当您针对用户操作调用 execute() 时，系统会生成一个令牌。对于关键用户事件（例如成功和失败的登录、注册以及已登录用户的操作），请创建评估来评估 execute() 调用的结果。评估会为您提供风险判定，您可以根据此判定来决定如何处理潜在的欺诈活动。您可以采取的一些措施包括：屏蔽可疑请求、验证有风险的登录尝试，以及调查感兴趣的账号。

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

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

用户标识符

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

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

经过哈希处理或加密

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

选择任意稳定的账号标识符，并在使用加密或哈希处理将其发送给 reCAPTCHA 之前，使其不透明：

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

除了为所有与账号相关的请求提供稳定的账号标识符之外，您还可以为某些特定请求提供额外的账号标识符（可能不稳定）。除了 accountId 之外，还提供特定于情境的账号标识符，有助于 reCAPTCHA 账号防御功能更好地分析用户活动并检测账号盗用尝试，从而保障用户账号的安全。当您提供其他标识符时，reCAPTCHA 会使用这些信息，通过标记滥用账号标识符并利用与这些标识符相关的跨网站滥用模式知识，基于跨网站模型来改进对用户账号的保护。例如，您可以提供以下信息：

用作登录句柄的用户名、电子邮件地址或手机号码，用于登录请求
针对多重身份验证请求验证的电子邮件地址或手机号码
用户在账号更新请求期间提供的电子邮件地址或手机号码（主手机号码或辅助手机号码）
用户在注册请求期间提供的电子邮件地址和手机号码

对于所有与账号相关的请求，请将所选的稳定账号标识符附加到 projects.assessments.create 方法中的 accountId 参数。（可选）在评估中使用 userIds 字段，为相关请求提供其他账号标识符。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目 ID
TOKEN：从 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,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 方法提供稳定的账号标识符，则可以继续这样做。不过，新集成应使用 accountId 参数，因为 hashedAccountId 已被弃用。

代码示例

Java

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


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;
  }
}

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

创建启用账号防御功能的评估时，账号防御功能会返回 accountDefenderAssessment 作为评估响应的一部分。accountDefenderAssessment 的值有助于您评估用户活动是合法的，还是欺诈活动。它还会返回一个评估 ID，您需要在注释用户事件时使用该 ID。

以下示例是一个 JSON 响应示例：

{
  "tokenProperties": {
    "valid": true,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 表示相应请求存在滥用账号创建行为的高风险。

值	说明
`SUSPICIOUS_LOGIN_ACTIVITY`	表示相应请求存在撞库攻击或账户接管（攻击）的高风险。
`SUSPICIOUS_ACCOUNT_CREATION`	表示相应请求存在滥用账号创建行为的高风险。
`PROFILE_MATCH`	表示用户的属性与之前看到的该用户的属性相符。此值表示相应用户使用的是之前曾用于访问您的移动应用的受信任设备。只有在以下情况下，系统才会返回 `PROFILE_MATCH`：您可以使用多重身份验证 (MFA) 或双重身份验证 (2FA)，reCAPTCHA 账号卫士会在用户通过 MFA 或 2FA 挑战后将用户个人资料标记为可信。您将评估注解为 `LEGITIMATE` 或 `PASSED_TWO_FACTOR`，并且 reCAPTCHA 账号卫士会将相应的用户个人资料标记为可信。

PROFILE_MATCH

表示用户的属性与之前看到的该用户的属性相符。此值表示相应用户使用的是之前曾用于访问您的移动应用的受信任设备。

只有在以下情况下，系统才会返回 PROFILE_MATCH：

您可以使用多重身份验证 (MFA) 或双重身份验证 (2FA)，reCAPTCHA 账号卫士会在用户通过 MFA 或 2FA 挑战后将用户个人资料标记为可信。
您将评估注解为 LEGITIMATE 或 PASSED_TWO_FACTOR，并且 reCAPTCHA 账号卫士会将相应的用户个人资料标记为可信。

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

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

为了向 reCAPTCHA 账号防御系统提供更多信息并改进网站专属检测模型，您必须通过创建评估来注释您评估的事件。

您可以通过向 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`" }

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

注意：以下命令假定您已使用您的用户账号通过运行 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

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


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) 风险评分功能会在账号防御评估中添加数值风险评分和直观易懂的说明。这些数据分析有助于您了解评估结果，并为后续行动或决策提供参考。

获取风险得分

如需接收风险得分和可解释性原因，请发送 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 选择阈值。性能可能会有所不同，因此您可能需要根据观察到的性能调整阈值。

预期 FPR	风险得分阈值
0.1%	1.0
0.25%	0.9
0.5%	0.8
1%	0.7
2%	0.6
4%	0.5
8%	0.4
15%	0.3
30%	0.2
60%	0.1
100%	0.0

调整阈值

如果观测到的假正例率过高，请提高阈值。如果观测到的召回率过低，但您可以容忍更高的 FPR，请降低阈值。

计算中间值

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

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%。

解读可解释性原因

可解释性原因可帮助您深入了解影响风险得分的因素。您可以根据这些原因来完善决策。

风险原因：表示与账户接管（攻击）风险增加相关的因素。
信任原因：表明可信度的因素。

任何风险得分都可能同时显示风险原因和信任原因。

原因	类型	解读
`PROFILE_MATCH`	信任	相应请求与此账号关联的可信个人资料相符。这相当于 `AccountDefenderLabel.PROFILE_MATCH` 标签。
`ACCOUNT_HISTORY_REPUTABLE`	信任	账号的历史活动信誉良好。该账号过去遭到盗用的可能性不大。
`CLIENT_HISTORICAL_BOT_ACTIVITY`	风险	我们发现，该客户端过去曾向此网站发送过类似机器人的流量。此原因纳入了历史声誉，表明已知相应客户端会使用机器人，即使当前请求是由人工发出的。
`ACCOUNT_IN_LARGE_RELATED_GROUP`	风险	相应账号属于一个大型的相关账号群组，表明该账号可能属于欺诈性网络。相关账号是根据流量模式和请求特征的相似性来确定的。
`CLIENT_ACCESSED_MANY_ACCOUNTS`	风险	我们发现，相应客户端已在此网站上访问过许多账号。

后续步骤

如需了解其他账号保护功能，请参阅用户账号保护功能。

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

准备工作

为 reCAPTCHA 账号防卫功能配置移动应用

报告关键用户操作

评估关键用户事件

用户标识符

经过哈希处理或加密

curl

PowerShell

代码示例

Java

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

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

curl

PowerShell

代码示例

Java

使用和解读账号盗用风险评分

获取风险得分

查看风险得分和详情

解读 ATO 风险得分

标准风险得分阈值

调整阈值

计算中间值

解读可解释性原因

后续步骤

检测并防范移动应用中的与账号相关的欺诈活动