偵測及防範網站上與帳戶相關的詐欺活動

本文說明如何使用 reCAPTCHA 帳戶防禦機制，偵測及防範網站上與帳戶相關的詐欺活動。

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

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

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

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

事前準備

為 reCAPTCHA 帳戶防護設定網頁

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

啟用水平遙測資料收集功能。
製作重要使用者動作報表。
評估重要使用者事件。
為使用者事件加上註解，調整網站專屬模型。

啟用水平遙測資料收集功能

reCAPTCHA 帳戶防護功能需要完整掌握使用者動作，例如使用者是否已登入或即將登入。如要啟用 reCAPTCHA Account Defense 功能，被動收集水平遙測資料，請在使用者工作流程的所有網頁背景中，載入您建立的評分型網站金鑰，以及 reCAPTCHA JavaScript 指令碼。

以下範例說明如何在網頁中載入 reCAPTCHA JavaScript 指令碼。

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

製作重要使用者動作報表

如要偵測可疑活動模式，並建立更完善的網站典型活動模式模型，reCAPTCHA 帳戶防護功能需要重要使用者動作的相關資訊。因此，請在網頁上發生重要使用者動作時呼叫 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 帳戶防護功能，您必須提供穩定的帳戶 ID，以便進行評估，並將使用者活動 (例如登入要求、已登入要求和註冊要求) 歸因於特定帳戶。這有助於 reCAPTCHA 帳戶防禦程序處理使用者活動模式，為每個帳戶建立活動模型，進一步偵測異常和濫用流量。

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

使用者 ID

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

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

雜湊處理或加密

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

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

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

除了為所有帳戶相關要求提供穩定的帳戶 ID，您還可以為特定要求提供其他帳戶 ID (可能不穩定)。除了 accountId 之外，您還可以提供特定情境的帳戶 ID，讓 reCAPTCHA 帳戶防護功能更準確地分析使用者活動，並偵測帳戶盜用嘗試，確保使用者帳戶安全無虞。提供額外 ID 時，reCAPTCHA 會根據跨網站模型，使用這些資訊改善使用者帳戶的防護機制，方法是標記濫用帳戶 ID，並運用與這些 ID 相關的跨網站濫用模式知識。例如，您可以提供下列資訊：

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

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

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

PROJECT_ID：您的 Google Cloud 專案 ID
TOKEN：從 grecaptcha.enterprise.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,
    "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 方法提供穩定的帳戶 ID，則可繼續使用。不過，新的整合作業應改用 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,
    "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)，且 reCAPTCHA Account Defense 功能會在使用者通過 MFA 或 2FA 驗證後，將使用者設定檔標示為可信任。您可以將評估結果註記為 `LEGITIMATE` 或 `PASSED_TWO_FACTOR`，reCAPTCHA 帳戶防護功能會將相應的使用者設定檔標示為信任。
`RELATED_ACCOUNTS_NUMBER_HIGH`	表示要求有大量相關帳戶。這不一定代表帳戶有問題，但可能需要進一步調查。

注意：如果 accountDefenderAssessment 欄位空白，表示 reCAPTCHA Account Defense 沒有任何可加入分數的項目。

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

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

如要為評估加上註解，請使用評估 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

如要向 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) 風險分數功能會在 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.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：

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% 的誤判率。

解讀可解釋性原因

可解釋性原因可深入瞭解影響風險分數的因素。運用這些原因修正決策。

風險原因：指出與帳戶遭入侵風險較高相關的因素。
信任原因：指出顯示合法性的因素。

任何風險分數都可能顯示風險和信任原因。

原因	類型	解釋
`PROFILE_MATCH`	信任	這項要求與這個帳戶相關聯的信任設定檔相符。這相當於 `AccountDefenderLabel.PROFILE_MATCH` 標籤。
`ACCOUNT_HISTORY_REPUTABLE`	信任	帳戶的歷史活動信譽良好。帳戶過去不太可能遭盜用。
`CLIENT_HISTORICAL_BOT_ACTIVITY`	風險	我們發現用戶端過去曾將類似機器人的流量傳送至這個網站。這個原因會納入過往信譽，並指出用戶端已知會使用機器人，即使目前的要求是由真人提出也一樣。
`ACCOUNT_IN_LARGE_RELATED_GROUP`	風險	這個帳戶與大量相關帳戶屬於同一群組，可能屬於詐欺網路。系統會根據相似的流量模式和要求特徵，找出相關帳戶。
`CLIENT_ACCESSED_MANY_ACCOUNTS`	風險	我們發現該用戶端在這個網站上存取多個帳戶。

後續步驟

使用 API 找出有相關行為的帳戶。

偵測及防範網站上與帳戶相關的詐欺活動 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

為 reCAPTCHA 帳戶防護設定網頁

啟用水平遙測資料收集功能

製作重要使用者動作報表

評估重要使用者事件

使用者 ID

雜湊處理或加密

curl

PowerShell

程式碼範例

Java

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

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

curl

PowerShell

程式碼範例

Java

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

取得風險分數

讀取風險分數和詳細資料

解讀 ATO 風險分數

標準風險分數門檻

調整起付額度

計算中繼值

解讀可解釋性原因

後續步驟

偵測及防範網站上與帳戶相關的詐欺活動