Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

チャレンジポリシーを構成する

このドキュメントでは、既存の Google Cloud Fraud Defense 統合を使用してチャレンジポリシーを構成する方法について説明します。

チャレンジポリシーを使用すると、カスタムルールに基づいて CAPTCHA チャレンジを選択的にトリガーできます。これらのルールは、リスクスコア、IP アドレス、ユーザーエージェント、ASN、または確認済みのボット（AI エージェント）の ID に基づいて、Fraud Defense チャレンジを表示するタイミングを決定します。

チャレンジポリシーは、次の推奨機能で使用できます。

AutoExecute 構成: クライアントアプリケーションの JavaScript 統合を簡素化します。
チャレンジ: チャレンジルールで必要な場合に、ユーザー確認をトリガーします。 Fraud Defense は、次のチャレンジタイプをサポートしています。
- ビジュアルチャレンジ: プロンプトに基づいて画像を選択するようユーザーに求めます。デフォルトでは、チャレンジオプションが選択された状態でルールが構成されている場合、ビジュアルチャレンジが選択されます。
- 音声チャレンジ: アクセシビリティの代替手段として、音声キューを識別するようユーザーに求めます。
- QR コードチャレンジ: モバイルデバイスで QR コードをスキャンしてチャレンジを解決するようユーザーに求めます。この機能を使用するには、ユニバーサルキーを許可リストに登録する必要があります。ユニバーサルキーを許可リストに追加するには、 fraud-defense@google.com の Fraud Defense チームに連絡して、ユニバーサルキーをお知らせください。

始める前に

Google Cloud Fraud Defense の環境を準備します。
プロジェクトに対して課金が有効になっていることを確認します Google Cloud 。課金は、クレジットカードまたは既存の Google Cloud プロジェクトの課金 ID を使用して有効にできます。課金についてサポートが必要な場合は、Cloud Billing サポートまでお問い合わせください。
プロジェクトのユニバーサルキーを作成または特定します。キーを作成するには、ユニバーサルキーを作成するをご覧ください。または、次のいずれかの手順で、既存のユニバーサルキーの ID をコピーできます。
- コンソールから既存のキーの ID をコピーするには、次の操作を行います。 Google Cloud
  1. コンソールで、[Google Cloud Fraud Defense] ページに移動します。 Google Cloud
    
    Fraud Defense に移動
  2. [reCAPTCHA キー] リストで、コピーするキーを見つけて、 [クリップボードにコピー] をクリックします。
- REST API を使用して既存のキーの ID をコピーするには、projects.keys.list メソッドを呼び出します。
- gcloud CLI を使用して既存のキーの ID をコピーするには、 gcloud recaptcha keys list コマンドを実行します。
保護するユーザーアクション（login、signup、password_reset など）と、ウェブサイトのどのページでこれらのアクションがトリガーされるかを特定して、Fraud Defense 統合を計画します。AutoExecute 構成を使用する場合は、これらのアクションが protected_endpoint_group で指定されたアクション名と一致していることを確認してください。
Fraud Defense をウェブページに統合します。Fraud Defense AutoExecute 構成を使用することをおすすめします。一般的な設定手順については、ウェブサイトにユニバーサルキーをインストールするをご覧ください。

Fraud Defense ポリシー構成の概要

Fraud Defense ポリシー構成を使用すると、Fraud Defense 保護の動作をカスタマイズできます。challenge_rule_groups セクションを使用してチャレンジポリシーを構成できます。

ポリシー構成の表示と更新は、 Google Cloud コンソール、gcloud CLI、または reCAPTCHA Enterprise REST API を使用して行うことができます。

コンソール

コンソールでポリシー構成を表示または更新するには、次の操作を行います。 Google Cloud

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

Fraud Defense に移動
リソースセレクタでプロジェクトが選択されていることを確認します。
[reCAPTCHA キー] テーブルで、チャレンジポリシーを構成するキーの名前をクリックします。
[キーの詳細] ページで、[ポリシー] タブに移動します。
[ルールグループ] セクションで、チャレンジルールと条件式を表示、追加、編集できます。
[保存] をクリックします。

gcloud

キーのポリシー構成を更新するには、gcloud alpha recaptcha policies update コマンドを実行します。

gcloud alpha recaptcha policies update --key=KEY_ID --policy=POLICY.yaml

キーの現在のポリシー構成を表示するには、gcloud alpha recaptcha policies describe コマンドを実行します。

gcloud alpha recaptcha policies describe --key=KEY_ID

REST API

キーのポリシー構成を更新するには、projects.keys.updatePolicy メソッドを呼び出します。

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

キーの現在のポリシー構成を表示するには、projects.keys.getPolicy メソッドを呼び出します。

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

ポリシー構成では、Google Cloud CLI には YAML 形式、REST API には JSON 形式が使用されます。challenge_rule_groups セクションの完全なスキーマについては、チャレンジポリシーを構成するをご覧ください。

さまざまなユースケースの例については、チャレンジルール構成の例をご覧ください。

チャレンジポリシーを構成する

チャレンジポリシーは、Fraud Defense ポリシー構成の challenge_rule_groups セクション内で構成します。ドメイン情報を含む client_settings を使用するポリシーがすでにある場合は、チャレンジポリシールールを含めるようにポリシーを更新できます。

challenge_rule_groups セクションの構造は次のとおりです。

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

すべてのチャレンジルールで、condition フィールドは省略可能です。condition が指定されていないか空の場合、ルールは無条件で適用されます。また、 challenge フィールドと no_challenge フィールドは相互に排他的であり、各ルールにいずれか 1 つが存在する必要があります。

ルールの評価順序

ルールグループとその内部ルールは、上から順に評価されます。最初に一致したルールが適用されます。インタラクションに一致するグループとルールがない場合、評価はデフォルトで標準評価になります。チャレンジは表示されませんが、リクエストのリスクスコアが生成されます。

チャレンジの難易度

チャレンジをトリガーするときに難易度を指定できます。有効な難易度の値の完全なリストについては、ChallengeSecurityPreference API リファレンスをご覧ください。

条件の構文

condition フィールドは、Common Expression Language（CEL）式としてフォーマットされた省略可能な文字列です。condition が指定されていないか空の場合、ルールは無条件で適用されます。CEL は、関係演算子（<、<=、>、>=、==、!=）、算術演算子（+、-、/、*、%）、論理演算子（!、&&、||）、コンテナ演算子（[]、in）など、標準の C 類似演算子を提供します。CEL は、一般的なプリミティブデータ型（bool、int、uint、double、string）、基本的なコンテナ型（lists、messages）、定数（true、1、0.5、"hello"、[1, 2, 3] など）をサポートしています。

ランタイムでは、次の Fraud Defense 変数にアクセスできます。

変数	型	説明
`score`	`double`	Fraud Defense ボットスコア。
`user_ip_address`	`string`	リクエストを行うユーザーの IP アドレス（IPv4 または IPv6）。
`user_agent`	`string`	リクエストを行うユーザーのユーザーエージェント。
`user_asn`	`int`	リクエストを行うユーザーの自律システム番号（ASN）。`AS` 接頭辞は省略します（`AS12345` ではなく `12345` を使用します）。
`verified_bots`	`list(Bot)`	Fraud Defense によって識別された、確認済みの自動クローラまたはエージェント（検索エンジンのインデクサ、AI 検索アシスタント、パートナーコンテンツスクレイパーなど）のリスト。

次の追加の非プリミティブ型が定義されています。値の完全なリストについては、ボットをご覧ください。

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

使用可能な name 値の詳細については、Bot API リファレンスをご覧ください。有効な bot_type 列挙値の詳細については、BotType API リファレンスをご覧ください。

Fraud Defense チャレンジポリシーでは、これらの変数を使用してブール式を作成できます。たとえば、score > 0.5、user_ip_address == "192.0.2.1"、user_asn == 12345 は、ブール値に評価される有効な条件式です。user_asn は整数型であるため、ASN を確認するときは AS 接頭辞を省略する必要があります。

Fraud Defense チャレンジポリシーの条件では、次の関数を使用できます。

名前	署名	説明
`contains`	`string.contains(string) -> bool`	文字列オペランドに部分文字列が含まれているかどうかを確認します。
`startsWith`	`string.startsWith(string) -> bool`	文字列オペランドが指定された接頭辞で始まるかどうかを確認します。
`endsWith`	`string.endsWith(string) -> bool`	文字列オペランドが指定された接尾辞で終わるかどうかを確認します。
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	文字列（コードポイント数）またはリスト（要素数）のサイズを返します。

包括関数は、CEL に組み込まれたマクロのスタイルです。次の包括が使用可能です。

名前	署名	説明	例
`has`	`has(message.field) -> bool`	フィールドが使用可能かどうかを確認します。	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	リスト `e` 内のすべての要素 `x` が述語 `p` と一致するかどうかを確認します。	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	リスト `e` 内の要素 `x` が述語 `p` と一致するかどうかを確認します。	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	リスト `e` 内の要素 `x` が述語 `p` と一致するかどうかを確認します。	`[1, 2, 2].exists_one(i, i < 2)`

チャレンジルール構成の例

このセクションでは、有効なチャレンジルール構成の例を示します。

スコアが低いすべてのリクエストにチャレンジする

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

スコアが低いすべてのリクエストに高摩擦チャレンジを選択する

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

スコアが低い特定のアクションにチャレンジする

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

アクションごとに異なるルールしきい値を構成する

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

許可リストに登録されている IP アドレスにチャレンジを表示しない

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

注: このルールは、 Fraud Defense IP 許可リスト機能とは異なります。

IP アドレスのサブネットにチャレンジを表示しない

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

特定の ASN からのリクエストにチャレンジを表示しない

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

Google エージェントにチャレンジを表示しない

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

複雑な条件に基づいてチャレンジを表示する

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

次のステップ

reCAPTCHA レスポンストークンを評価するには、ウェブサイトの評価を作成するをご覧ください。

チャレンジ ポリシーを構成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

Fraud Defense ポリシー構成の概要

コンソール

gcloud

REST API

チャレンジ ポリシーを構成する

ルールの評価順序

チャレンジの難易度

条件の構文

チャレンジルール構成の例

スコアが低いすべてのリクエストにチャレンジする

スコアが低いすべてのリクエストに高摩擦チャレンジを選択する

スコアが低い特定のアクションにチャレンジする

アクションごとに異なるルールしきい値を構成する

許可リストに登録されている IP アドレスにチャレンジを表示しない

IP アドレスのサブネットにチャレンジを表示しない

特定の ASN からのリクエストにチャレンジを表示しない

Google エージェントにチャレンジを表示しない

複雑な条件に基づいてチャレンジを表示する

次のステップ

チャレンジポリシーを構成する

チャレンジポリシーを構成する