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

プレビュー

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

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

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

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

• AutoExecute 構成: クライアント アプリケーションの JavaScript 統合を簡素化します。
• チャレンジ: チャレンジ ルールで必要な場合にユーザー確認をトリガーします。Fraud Defense は、次のチャレンジ タイプをサポートしています。
  • 視覚的なチャレンジ: プロンプトに基づいて画像を選択するようユーザーに求めます。デフォルトでは、チャレンジ オプションが選択されたルールが構成されると、視覚的なチャレンジが選択されます。
  • 音声チャレンジ: アクセシビリティの代替手段として、音声キューを特定するようユーザーに求めます。
  • QR コード チャレンジ: モバイル デバイスで QR コードをスキャンしてチャレンジをクリアするようユーザーに求めます。この機能を使用するには、ユニバーサル キーが許可リストに登録されている必要があります。ユニバーサル キーを許可リストに追加するには、[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. [reCAPTCHA キー] リストで、コピーするキーを見つけて [ クリップボードにコピー] をクリックします。

   • 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 フィールドは相互に排他的であり、各ルールにはどちらか一方のみが存在する必要があります。

ルールの評価順序

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

チャレンジの難易度

課題を開始する際に難易度を指定できます。有効な難易度の値の一覧については、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 検索アシスタント、パートナー コンテンツ スクレイパーなど）のリスト。

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

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, 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: {}

注: このルールは、不正行為対策の 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 レスポンス トークンを評価するには、ウェブサイトの評価を作成するをご覧ください。