Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

偵測及防範行動應用程式中的帳戶相關詐欺活動

本文說明如何使用帳戶防禦功能，偵測及防範行動應用程式中與帳戶相關的詐欺活動。

Fraud Defense 可協助您保護重要動作，例如登入和結帳。不過，只要觀察特定使用者在一段時間內於行動應用程式中的行為，就能偵測到許多細微的帳戶濫用行為。Account Defense 是 Fraud Defense 的一項功能，可為您的行動應用程式建立網站專屬模型，偵測可疑行為趨勢或活動變化，協助您找出這類細微的濫用行為。這項工具會使用網站專屬模型，協助您偵測下列情況：

可疑活動
行為相似的帳戶
來自下列類型裝置的要求：已標為特定使用者信任的來源

根據帳戶防禦和網站專屬模型的分析結果，您可以採取下列行動：

限制或停用詐欺帳戶。
防範帳戶入侵行為。
減少帳戶遭盜用的情況。
只允許來自正當使用者帳戶的要求。
減少使用者透過信任的裝置登入時遇到的阻礙。

事前準備

在專案中新增帳單帳戶，觸發自動安全性審查後，即可使用行動應用程式的帳戶防護功能。如要將行動應用程式加入這項功能，請將帳單帳戶新增至專案。
準備 Google Cloud Fraud Defense 環境。
建立分數型金鑰。

為行動應用程式設定帳戶防護工具

帳戶防護工具需要全面瞭解帳戶活動，才能有效偵測。如要開始將帳戶相關活動提供給 Account Defense，以及建立及改善網站專用模型，請按照下列步驟操作：

將 Fraud Defense 整合至行動應用程式。
- 如果是 Android 應用程式，請參閱「將 Fraud Defense 整合至 Android 應用程式」。
- 如果是 iOS 應用程式，請參閱「將 Fraud Defense 整合至 iOS 應用程式」。
製作重要使用者動作報表。
評估重要使用者事件。
為使用者事件加上註解，調整網站專屬模型。

製作重要使用者動作報表

為偵測可疑活動模式，並建立更完善的網站一般活動模式模型，帳戶防禦功能需要重要使用者動作的相關資訊。針對應用程式中受 Fraud Defense 保護的每個動作，使用 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() 呼叫的結果。評估結果會提供風險判定，您可以根據這項判定，決定如何處理潛在的詐欺活動。您可以採取下列行動：封鎖可疑要求、驗證高風險登入行為，以及調查感興趣的帳戶。

帳戶防護功能需要您提供穩定的帳戶 ID，才能進行評估，並將使用者活動 (例如登入要求、已登入要求和註冊要求) 歸因於特定帳戶。這有助於帳戶防禦程序處理使用者活動模式，為每個帳戶建立活動模型，進一步偵測異常和濫用流量。

選擇使用者不會經常變更的穩定帳戶 ID accountId，並在 projects.assessments.create 方法中提供給評估作業。對於與同一位使用者相關的所有事件，這個穩定帳戶 ID 的值應相同。您可以提供下列資訊做為帳戶 ID：

使用者 ID

如果每個帳戶都能與穩定的使用者名稱、電子郵件地址或電話號碼建立專屬關聯，您就可以將這些資訊做為 accountId。當您提供這類跨網站 ID (可在不同網站重複使用的 ID) 時，Fraud Defense 會使用這項資訊，根據跨網站模型標記濫用帳戶 ID，並運用與這些 ID 相關的跨網站濫用模式知識，加強保護使用者帳戶。

或者，如果每個帳戶都有專屬的內部使用者 ID，您可以將該 ID 提供為 accountId。

雜湊處理或加密

如果沒有與每個帳戶唯一相關聯的內部使用者 ID，您可以將任何穩定 ID 轉換為不透明的網站專屬帳戶 ID。Fraud Defense 帳戶防護工具仍需使用這個 ID，才能瞭解使用者活動模式並偵測異常行為，但這個 ID 不會與其他網站共用。

選取任何穩定的帳戶 ID，並使用加密或雜湊函式，在傳送至 Fraud Defense 前將其設為不透明：

加密 (建議)：使用確定性加密方法加密帳戶 ID，產生穩定的密文。如需詳細操作說明，請參閱「以決定性方式加密資料」。選擇對稱式加密而非雜湊處理時，您不需要保留使用者 ID 與對應不透明使用者 ID 之間的對應關係。解密 Fraud Defense 傳回的不透明 ID，將其轉換為使用者 ID。
雜湊處理：建議使用 SHA256-HMAC 方法，並搭配您選擇的自訂鹽值，對帳戶 ID 進行雜湊處理。由於雜湊值只能單向轉換，您必須保留產生的雜湊值與使用者 ID 之間的對應關係，才能將傳回的雜湊帳戶 ID 對應回原始帳戶。

除了為所有帳戶相關要求提供穩定的帳戶 ID，您也可以為某些特定要求提供額外的帳戶 ID (可能不穩定)。除了 accountId 之外，系統還會提供特定情境的帳戶 ID，協助 Account Defense 更準確地分析使用者活動，並偵測帳戶入侵嘗試，確保使用者帳戶安全。提供額外 ID 後，Google Cloud Fraud Defense 會使用這些資訊，根據跨網站模型標記濫用帳戶 ID，並運用與這些 ID 相關的跨網站濫用模式知識，加強保護使用者帳戶。例如，您可以提供下列資訊：

使用者名稱、電子郵件地址或電話號碼，用於登入要求中的登入控制代碼
已通過驗證的電子郵件地址或電話號碼，用於多重驗證要求
使用者在帳戶更新要求中提供的電子郵件地址或電話號碼 (主要或次要)
使用者在註冊要求期間提供的電子郵件地址和電話號碼

在所有帳戶相關要求中，將所選的穩定帳戶 ID 附加至 projects.assessments.create 方法的 accountId 參數。視需要使用評估中的 userIds 欄位，為相關要求提供其他帳戶 ID。

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：您的 Google Cloud 專案 ID
TOKEN：從 execute() 呼叫傳回的權杖
KEY_ID：與應用程式相關聯的 reCAPTCHA 金鑰
ACCOUNT_ID：與使用者帳戶建立專屬關聯的 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 方法提供穩定的帳戶 ID，可以繼續使用。不過，新的整合作業應改用 accountId 參數，因為 hashedAccountId 已淘汰。

程式碼範例

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

解讀重大使用者事件的風險判定結果

啟用帳戶防護功能後建立評估時，帳戶防護功能會在評估回應中傳回 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)，在使用者通過 MFA 或 2FA 驗證後，將使用者設定檔標示為信任。您可以將評估結果標註為 `LEGITIMATE` 或 `PASSED_TWO_FACTOR`，帳戶防護功能會將相應的使用者設定檔標示為信任。

PROFILE_MATCH

表示使用者的屬性與這位使用者先前看到的屬性相符。這個值表示使用者目前使用的裝置是先前用來存取行動應用程式的信任裝置。

只有在下列情況下，系統才會傳回 PROFILE_MATCH：

您可以使用多重驗證 (MFA) 或雙重驗證 (2FA)，在使用者通過 MFA 或 2FA 驗證後，將使用者設定檔標示為信任。
您可以將評估結果標註為 LEGITIMATE 或 PASSED_TWO_FACTOR，帳戶防護功能會將相應的使用者設定檔標示為信任。

注意：如果 accountDefenderAssessment 欄位空白，表示帳戶防禦功能沒有任何項目可加入分數。

為事件加上註解，調整網站專屬模型

如要向帳戶防護提供更多資訊，並改善網站專用偵測模型，請建立評估項目，為您評估的事件加上註解。

如要為評估加上註解，請使用評估 ID，向 projects.assessments.annotate 方法傳送要求。在該要求的內文中，您會加入標籤，提供評估中所述事件的額外資訊。

如要為評估作業加上註解，請按照下列步驟操作：

視用途而定，決定要在要求 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：選用。與您應用程式中的使用者帳戶建立關聯的專屬 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) 風險分數功能會在帳戶防禦評估中，加入數值風險分數和使用者可理解的說明。這些洞察資料有助於瞭解評估結果，並據此採取後續行動或做出決策。

取得風險分數

如要取得風險分數和可解釋性原因，請傳送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 風險分數，取代 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`	風險	我們發現該用戶端在這個網站上存取多個帳戶。

調整帳戶入侵風險門檻

評估流量中的帳戶盜用風險分數後，您可能需要調整門檻，以達到可接受的偽陽率 (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 為 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% 的誤判率。

後續步驟

如要瞭解其他帳戶保護功能，請參閱「使用者帳戶保護功能」。

偵測及防範行動應用程式中的帳戶相關詐欺活動 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

為行動應用程式設定帳戶防護工具

製作重要使用者動作報表

評估重要使用者事件

使用者 ID

雜湊處理或加密

curl

PowerShell

程式碼範例

Java

解讀重大使用者事件的風險判定結果

為事件加上註解，調整網站專屬模型

curl

PowerShell

程式碼範例

Java

使用及解讀帳戶入侵風險分數

取得風險分數

讀取風險分數和詳細資料

解讀帳戶盜用風險分數

標準風險分數門檻

解讀可解釋性原因

調整帳戶入侵風險門檻

調整起付額度

計算中間值

後續步驟

偵測及防範行動應用程式中的帳戶相關詐欺活動