モバイルアプリでのアカウント関連の不正行為の検出と防止

このドキュメントでは、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 アカウント保護では、ユーザーアクティビティ（ログインリクエスト、ログイン済みリクエスト、登録リクエストなど）を特定のアカウントに関連付けるために、安定したアカウント 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: 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,
    "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 メソッドで安定したアカウント識別子を提供している場合は、そのまま使用し続けることができます。ただし、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,
    "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）または 2 要素認証（2FA）を使用し、ユーザーが MFA チャレンジまたは 2FA チャレンジに合格したら、reCAPTCHA アカウント保護機能でユーザープロファイルを信頼できるとしてマークします。評価に `LEGITIMATE` または `PASSED_TWO_FACTOR` アノテーションを付け、reCAPTCHA アカウント保護機能は対応するユーザープロファイルを信頼できるとしてマークします。

PROFILE_MATCH

ユーザーの属性が、この特定のユーザーの以前に確認された属性に一致することを示します。この値は、このユーザーが以前モバイルアプリにアクセスするために使用した信頼できるデバイス上にいることを示します。

PROFILE_MATCH は、次のシナリオでのみ返されます。

多要素（MFA）または 2 要素認証（2FA）を使用し、ユーザーが MFA チャレンジまたは 2FA チャレンジに合格したら、reCAPTCHA アカウント保護機能でユーザープロファイルを信頼できるとしてマークします。
評価に LEGITIMATE または PASSED_TWO_FACTOR アノテーションを付け、reCAPTCHA アカウント保護機能は対応するユーザープロファイルを信頼できるとしてマークします。

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

アカウントの乗っ取りリスクスコアを使用し、解釈する

アカウントの乗っ取り（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 ラベルの代わりに ATO リスクスコアを使用します。同じ評価でリスクスコアとラベルの両方を使用して強制措置をトリガーしないでください。適用ロジックは、リスクスコアがしきい値を超えた場合、またはラベルが存在する場合に基づいて構成できます。一般的に、リスクスコアはより詳細な評価を提供します。

リスクスコアを適用する前に、プラットフォームのトラフィックで適切なしきい値を使用してリスクスコアのパフォーマンスを評価することをおすすめします。

リスクスコアに基づいて処理を行うには、次のスニペットに示すように、バックエンドにチェックを実装します。

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 の増加を許容できるのであれば、しきい値を下げます。

中間値を計算する

標準値間のしきい値の 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 のしきい値を見つけるには、標準値の間を補間します。次の例は、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 では、FPR が 5% になると推定されます。

説明可能性の理由を解釈する

説明可能性の理由は、リスクスコアに影響を与える要因に関する分析情報を提供します。これらの理由を参考に、意思決定を改善してください。

リスクの理由: アカウントの乗っ取りリスクが高まる要因を示します。
信頼の理由: 正当性を示す要因を示します。

リスクスコアには、リスクの理由と信頼の理由の両方が表示されることがあります。

理由	タイプ	解釈
`PROFILE_MATCH`	信頼	リクエストが、このアカウントに関連付けられている信頼できるプロファイルと一致します。これは `AccountDefenderLabel.PROFILE_MATCH` ラベルと同じです。
`ACCOUNT_HISTORY_REPUTABLE`	信頼	アカウントの過去のアクティビティが信頼できるものである。過去にアカウントが不正使用された可能性は低い。
`CLIENT_HISTORICAL_BOT_ACTIVITY`	リスク	このクライアントは過去にこのサイトにボットのようなトラフィックを送信していることが確認されています。この理由は過去の評判を考慮したもので、現在のリクエストが人間によって行われている場合でも、クライアントが bot を使用していることがわかっていることを示します。
`ACCOUNT_IN_LARGE_RELATED_GROUP`	リスク	アカウントが関連アカウントの大きなグループの一部である。これは、不正なネットワークの一部である可能性があることを示しています。関連アカウントは、トラフィックパターンとリクエストの特性が類似していることに基づいて特定されます。
`CLIENT_ACCESSED_MANY_ACCOUNTS`	リスク	このサイトで、クライアントが多数のアカウントにアクセスしていることが確認されました。

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

reCAPTCHA アカウント保護用にモバイルアプリを構成したら、reCAPTCHA アカウント保護を有効にできます。

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

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

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

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

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

次のステップ

その他のアカウント保護機能については、ユーザーアカウント保護機能をご覧ください。

モバイルアプリでのアカウント関連の不正行為の検出と防止 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

reCAPTCHA アカウント保護用にモバイルアプリを構成する

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

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

ユーザー識別子

ハッシュ化と暗号化

curl

PowerShell

コードサンプル

Java

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

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

curl

PowerShell

コードサンプル

Java

アカウントの乗っ取りリスクスコアを使用し、解釈する

リスクスコアを取得する

リスクスコアと詳細を読む

ATO リスクスコアを解釈する

標準リスクスコアのしきい値

しきい値を調整する

中間値を計算する

説明可能性の理由を解釈する

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

次のステップ

モバイルアプリでのアカウント関連の不正行為の検出と防止

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

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

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