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

プレビュー

このプロダクトまたは機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前サービス規約」の対象となります。pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

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

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

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

• AutoExecute 構成: クライアント アプリケーションの JavaScript 統合を簡素化します。
• チャレンジ: チャレンジルールで必要な場合にユーザー確認をトリガーします。Fraud Defense は、次のチャレンジ タイプをサポートしています。
  • 視覚的なチャレンジ: プロンプトに基づいて画像を選択するようユーザーに求めます。デフォルトでは、チャレンジ オプションを選択してルールを構成すると、ビジュアル チャレンジが選択されます。
  • 音声チャレンジ: ユーザー補助の代替手段として、音声による音声キューを識別するようユーザーに依頼します。
  • QR コード チャレンジ: ユーザーにモバイル デバイスで QR コードをスキャンしてチャレンジを解決するよう依頼します。この機能を使用するには、ユニバーサル キーが許可リストに登録されている必要があります。ユニバーサル キーを許可リストに追加するには、Fraud Defense チーム（[e-mail]）に連絡して、ユニバーサル キーを提供してください。

始める前に

1. Google Cloud Fraud Defense の環境を準備する。
2. Google Cloud プロジェクトで課金が有効になっていることを確認します。課金は、クレジット カードまたは既存の Google Cloud プロジェクトの請求 ID を使用して有効にできます。課金についてサポートが必要な場合は、Cloud Billing サポートまでお問い合わせください。

3. プロジェクトのユニバーサル キーを作成または特定します。鍵を作成するには、ユニバーサル鍵を作成するをご覧ください。または、次のいずれかの手順で、既存のユニバーサル キーの ID をコピーすることもできます。

   • Google Cloud コンソールから既存のキーの ID をコピーするには、次の操作を行います。

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

        [Fraud Defense] に移動

     2. [キー] リストで、コピーするキーを見つけて、 [クリップボードにコピー] をクリックします。

   • REST API を使用して既存のキーの ID をコピーするには、projects.keys.list メソッドを呼び出します。

   • gcloud CLI を使用して既存のキーの ID をコピーするには、gcloud recaptcha keys list コマンドを実行します。

4. 保護するユーザー アクション（login、signup、password_reset など）と、これらのアクションをトリガーするウェブサイトのページを特定して、Fraud Defense の統合を計画します。AutoExecute 構成を使用する場合は、これらのアクションが protected_endpoint_group で指定されたアクション名と一致していることを確認してください。

5. Fraud Defense をウェブページに統合します。Fraud Defense の AutoExecute 構成を使用することをおすすめします。一般的な設定手順については、ウェブサイトにユニバーサル キーをインストールするをご覧ください。

Fraud Defense ポリシー構成の概要

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

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

コンソール

Google Cloud コンソールでポリシー構成を表示または更新する手順は次のとおりです。

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

   [Fraud Defense] に移動

2. リソース セレクタでプロジェクトが選択されていることを確認します。

3. [reCAPTCHA キー] テーブルで、チャレンジ ポリシーを構成するキーの名前をクリックします。

4. [鍵の詳細] ページで、[ポリシー] タブに移動します。

5. [ルールグループ] セクションでは、チャレンジ ルールと条件式を表示、追加、編集できます。

6. [保存] をクリックします。

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 の bot スコア。
user_ip_address	string	リクエストを行っているユーザーの IP アドレス（IPv4 または IPv6）。
user_agent	string	リクエストを行っているユーザーのユーザー エージェント。
user_asn	int	リクエストを行うユーザーの自律システム番号（ASN）。AS 接頭辞は省略します（たとえば、AS12345 ではなく 12345 を使用します）。
region_code	string	リクエストの場所に関連付けられた Unicode CLDR リージョン コード（ISO 3166-1 alpha-2 に基づく）（例: "US"、"CA"、"FR"）。
verified_bots	list(Bot)	Fraud Defense によって識別された、確認済みの自動クローラまたはエージェント（検索エンジンのインデクサ、AI 検索アシスタント、パートナー コンテンツ スクレイパーなど）のリスト。

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

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"、region_code == "US"、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 つだけかどうかを確認します。	[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 の応答トークンを評価するには、ウェブサイトの評価を作成するをご覧ください。