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

このドキュメントでは、reCAPTCHA のアカウント保護機能を使用して、ウェブサイトでのアカウント関連の不正行為を検出して防止する方法について説明します。

reCAPTCHA は、ログインや購入手続きなど、重要なアクションの保護に役立ちます。しかし、アカウントの不正使用には、ウェブサイトで特定ユーザーの行動を一定期間観察することで検出できる捉えにくい形式が多数存在します。reCAPTCHA のアカウント保護機能は、ウェブサイトに対するサイト固有のモデルを作成し、不審な動作の傾向やアクティビティの変化を検出することで、この種の捉えにくい不正行為の特定をサポートします。サイト固有のモデルを使用すると、reCAPTCHA のアカウント保護機能によって次に挙げることの検出が容易になります。

不審なアクティビティ
類似した動作のアカウント
特定のユーザーに対して信頼できるとマークされたデバイスからのリクエスト

reCAPTCHA のアカウント保護機能とサイト固有のモデルの分析に基づいて、次のことを行えます。

不正なアカウントを制限または無効にする。
アカウントの乗っ取りの試みを防ぐ。
正常なアカウントの乗っ取りを軽減する。
正当なユーザーアカウントからのリクエストにのみアクセスを許可する。
信頼できるデバイスからのユーザーログインをスムーズにする。

始める前に

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

reCAPTCHA のアカウント保護機能では、効果的な検出を可能にするために、アカウントアクティビティを包括的に理解する必要があります。アカウント関連のアクティビティを reCAPTCHA のアカウント保護機能に供給し、サイト固有のモデルを作成して改善するには、次の手順を行います。

横方向のテレメトリーデータの収集を有効にする。
重要なユーザーアクションに関するレポートを行う。
重要なユーザーイベントを評価する。
ユーザーイベントにアノテーションを付け、サイト固有のモデルを調整する。

横方向のテレメトリーデータの収集を有効にする

reCAPTCHA のアカウント保護機能は、ユーザーがログインしているか、あるいはログインに誘導しているかなど、ユーザーの操作を完全に把握する必要があります。reCAPTCHA のアカウント保護機能による水平テレメトリーデータのパッシブ収集を有効にするには、ユーザーワークフローの一部であるすべてのウェブページのバックグラウンドで作成したスコアベースのサイトキーを使用して、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 として、以下を指定できます。

ユーザー識別子

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

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

ハッシュ化と暗号化

各アカウントに一意に関連付けられた内部ユーザー ID がない場合は、安定した識別子を不透明なサイト固有のアカウント識別子にできます。この識別子は、reCAPTCHA のアカウント保護機能がユーザーアクティビティパターンを把握して異常な動作を検出するために引き続き必要ですが、他のサイトと共有されることはありません。

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

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

アカウント関連のすべてのリクエストに安定したアカウント ID を提供するだけでなく、一部の特定のリクエストには変更できない可能性のある追加アカウント ID を指定できます。accountId に加えて提供されるコンテキスト固有のアカウント ID は、reCAPTCHA のアカウント保護機能がユーザーアクティビティをより深く理解し、ユーザーアカウントを安全に保つためのアカウントの乗っ取りの試みを検出するのに役立ちます。追加の ID を指定すると、reCAPTCHA はこの情報を使用して、不正なアカウント 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 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 を提供している場合は、そのまま使用し続けることができます。ただし、hashedAccountId は非推奨のため、新しい統合では代わりに accountId パラメータを使用する必要があります。

コードサンプル

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

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

注: accountDefenderAssessment フィールドが空の場合、reCAPTCHA のアカウント保護機能には、スコアに追加する情報がないことを示しています。

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

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

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


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

reCAPTCHA のアカウント保護機能を有効にする

reCAPTCHA のアカウント保護機能用にウェブページを構成すると、reCAPTCHA のアカウント保護機能を有効にできます。

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

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

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

注: Google Cloud コンソールでこの機能を有効にできない場合は、プロジェクトに請求先アカウントを追加して、自動セキュリティレビューをトリガーします。

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

次のステップ

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

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

始める前に

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

横方向のテレメトリー データの収集を有効にする

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

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

ユーザー識別子

ハッシュ化と暗号化

curl

PowerShell

コードサンプル

Java

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

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

curl

PowerShell

コードサンプル

Java

reCAPTCHA のアカウント保護機能を有効にする

次のステップ

横方向のテレメトリーデータの収集を有効にする

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

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

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