ウェブサイトでのアカウント関連の不正行為の検出と防止

このドキュメントでは、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 のアカウント保護では、ユーザーアクティビティ（ログインリクエスト、ログインリクエスト、登録リクエストなど）を特定のアカウントに関連付けるために、安定したアカウント ID を指定する必要があります。これにより、reCAPTCHA Enterprise のアカウント保護はユーザーアクティビティパターンを理解し、アカウントごとにアクティビティモデルを構築して、異常なトラフィックや不正なトラフィックをより適切に検出できます。

ユーザーが頻繁に変更しない固定のアカウント ID accountId を選択し、 projects.assessments.create メソッドで評価を指定します。この固定アカウント ID は、同じユーザーに関連するすべてのイベントで同じ値を持つ必要があります。アカウント ID として以下を指定できます。

ユーザー識別子

すべてのアカウントを固定のユーザー名、メールアドレス、電話番号に一意に関連付けることができる場合は、accountId として使用できます。このようなクロスサイト ID（サイト間で再利用できる ID）を指定すると、reCAPTCHA Enterprise がこの情報を使用して、不正なアカウント ID にフラグを立て、クロスサイトモデルに基づいてユーザーアカウントの保護を強化し、これらの識別子に関連するクロスサイト不正行為のパターンに関する知識を活用します。

また、各アカウントに一意に関連付けられた内部ユーザー ID がある場合は、accountId として指定できます。

ハッシュ化または暗号化

各アカウントに一意に関連付けられた内部ユーザー ID がない場合は、任意の固定 ID を不透明なサイト固有のアカウント ID に変換できます。この ID は、reCAPTCHA Enterprise のアカウント保護がユーザーアクティビティパターンを理解し、異常な動作を検出するために引き続き必要ですが、他のサイト間で共有されません。

暗号化またはハッシュ化を使用して、reCAPTCHA Enterprise に送信する前に、安定したアカウント ID を選択し、不透明にします。

暗号化（推奨）:安定した暗号テキストを生成する決定的な暗号化方法を使用して、アカウント ID を暗号化します。詳細な手順については、データを確定的に暗号化するをご覧ください。ハッシュ化ではなく対称暗号化を選択した場合、ユーザー ID と対応する不透明なユーザー ID とのマッピングを維持する必要はありません。reCAPTCHA Enterprise から返される不透明な識別子を復号して、ユーザー ID に変換します。
ハッシュ化: SHA256-HMAC メソッドを使用して、任意のカスタムソルトでアカウント ID をハッシュ化することをおすすめします。ハッシュは一方向のため、生成されたハッシュとユーザー ID の間のマッピングを維持する必要があります。これにより、元のアカウントに返されるハッシュ化されたアカウント ID をマッピングできます。

アカウント関連のすべてのリクエストに安定したアカウント ID を提供するだけでなく、一部の特定のリクエストには変更できない可能性のある追加アカウント ID を指定できます。accountId に加えて提供されるコンテキスト固有のアカウント ID は、reCAPTCHA Enterprise アカウント保護がユーザーアクティビティをより深く理解し、ユーザーアカウントを安全に保つためのアカウントの乗っ取りの試みを検出するのに役立ちます。追加の ID を指定すると、reCAPTCHA Enterprise はこの情報を使用して、不正なアカウント ID にフラグを付け、これらの識別子に関連するクロスサイトへの不正行為パターンの知識を使用して、クロスサイトモデルに基づいてユーザーアカウントの保護を向上させます。たとえば、次の情報を指定できます。

ログインリクエストのログインハンドルとして使用されたユーザー名、メールアドレス、または電話番号。
多要素認証リクエストのために確認済みのメールアドレスまたは電話番号
アカウントの更新リクエスト中にユーザーが指定したメールアドレスまたは電話番号（メインまたはセカンダリ）
登録リクエストでユーザーが指定したメールアドレスと電話番号

アカウント関連のすべてのリクエストについて、選択した固定アカウント ID を projects.assessments.create メソッドの accountId パラメータに追加します。必要に応じて、評価の userIds フィールドを使用して、関連するリクエストの追加アカウント ID を指定します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID
TOKEN: grecaptcha.enterprise.execute() 呼び出しから返されたトークン
KEY_ID: サイトに関連付けられている reCAPTCHA キー
ACCOUNT_ID: ユーザーアカウントとウェブサイトの関連付けのためにユーザーアカウントに一意に関連付けられた不透明な識別子
EMAIL_ADDRESS: 省略可。このリクエストに関連付けられているメールアドレス（存在する場合）。
PHONE_NUMBER: 省略可。このリクエストに関連付けられている電話番号（存在する場合）
USERNAME: 省略可。このリクエストに関連付けられているユーザー名（ある場合）

HTTP メソッドと URL:

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次のコマンドを実行して、ユーザーアカウントで CLI を使用します。gcloud init または gcloud auth login 。 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

reCAPTCHA Enterprise への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


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/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/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/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/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 も返します。

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）または 2 要素認証（2FA）を使用し、ユーザーが MFA または 2FA チャレンジに合格したら、reCAPTCHA Enterprise のアカウント保護はユーザープロファイルを信頼できるとしてマークします。評価に `LEGITIMATE` または `PASSED_TWO_FACTOR` アノテーションを付け、reCAPTCHA Enterprise のアカウント保護は対応するユーザープロファイルを信頼できるとしてマークします。
`RELATED_ACCOUNTS_NUMBER_HIGH`	リクエストに多数の関連アカウントがあることを示します。必ずしもそのアカウントが不正であることを意味するわけではありませんが、さらに調査が必要になる場合があります。

注: accountDefenderAssessment フィールドが空の場合、reCAPTCHA Enterprise のアカウント保護はスコアに追加するものがなかったことを示します。

イベントにアノテーションを付けてサイト固有のモデルを調整する

reCAPTCHA Enterprise のアカウント保護に詳細情報を提供し、サイト固有の検出モデルを改善するには、評価を作成して評価したイベントにアノテーションを付ける必要があります。

評価にアノテーションを付けるには、評価 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: 省略可。ウェブサイトのユーザーアカウントに一意に関連付けられた識別子。
詳細については、アノテーションのラベルをご覧ください。

HTTP メソッドと URL:
```
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次のコマンドを実行して、ユーザーアカウントで CLI を使用します。gcloud init または gcloud auth login 。 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


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

reCAPTCHA Enterprise のアカウント防御を有効にする

reCAPTCHA Enterprise のアカウント保護用にウェブページを構成したら、reCAPTCHA Enterprise アカウント保護を有効にできます。

Google Cloud コンソールで、[reCAPTCHA Enterprise] ページに移動します。

[reCAPTCHA Enterprise] に移動
ページの上部にあるリソースセレクタにリソース名が表示されていることを確認します。

プロジェクトの名前が表示されない場合は、リソースセレクタをクリックしてプロジェクトを選択します。
[設定] をクリックします。
[アカウント防御] ペインで [有効にする] をクリックします。
[アカウント防御の構成] ダイアログで [有効にする] をクリックします。

注: Google Cloud コンソールでこの機能を有効にできない場合は、営業チームに問い合わせて、セキュリティレビューを開始するように依頼してください。

reCAPTCHA Enterprise のアカウント保護の有効化は、システムに反映されるまで数時間かかる場合があります。機能の有効化が Google のシステムに反映されると、評価の一環としてアカウント防御に関連するレスポンスを受信し始めます。

次のステップ

API を使用して、関連する動作を示すアカウントを特定します。

ウェブサイトでのアカウント関連の不正行為の検出と防止

準備

reCAPTCHA Enterprise のアカウント保護用にウェブページを構成する

水平テレメトリー データの収集を有効にする

重要なユーザー アクションに関するレポートを行う

重要なユーザー イベントを評価する

ユーザー識別子

ハッシュ化または暗号化

curl

PowerShell

コードサンプル

Java

重要なユーザー イベントのリスク判定を解釈する

イベントにアノテーションを付けてサイト固有のモデルを調整する

curl

PowerShell

コードサンプル

Java

reCAPTCHA Enterprise のアカウント防御を有効にする

次のステップ

水平テレメトリーデータの収集を有効にする

重要なユーザーアクションに関するレポートを行う

重要なユーザーイベントを評価する

重要なユーザーイベントのリスク判定を解釈する