Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

ユニバーサルキーをウェブページにインストールする

Fraud Defense ユニバーサルキーは、自動 bot 攻撃、認証情報の不正使用、不正行為からウェブアプリケーションと API エンドポイントを保護するのに役立ちます。ユニバーサルキーを使用すると、自動ネットワークリクエストインターセプト（AutoExecute）、手動 JavaScript 実行、またはその両方の方法を組み合わせて、ウェブサイト全体に保護をデプロイできます。

始める前に

Google Cloud Fraud Defense の環境を準備する。
ユニバーサルキーを作成する。
ユニバーサルキーのドメインを構成します。
Google Cloud コンソールで保護されたエンドポイントの [ステータス] 列を表示するには、Cloud Monitoring の monitoring.timeSeries.list 権限があることを確認してください。この権限は、事前定義された Fraud Defense ロール（reCAPTCHA Enterprise 管理者、reCAPTCHA Enterprise 編集者、reCAPTCHA Enterprise 閲覧者）に含まれています。

ウェブサイトにユニバーサルキーをインストールする

ユニバーサルキーをインストールしてウェブページを保護するには、AutoExecute 構成、手動 JavaScript インストール、または同じユニバーサルキーを使用して異なるエンドポイントで両方の方法を組み合わせて使用できます。

AutoExecute 構成（推奨）: 構成された URL パスへの非同期ネットワークリクエストを自動的にインターセプトし、reCAPTCHA トークンをリクエストヘッダーに添付します。
手動インストール: 手動の grecaptcha.enterprise.execute() 呼び出しまたは HTML ボタン属性を使用します。このメソッドは、単独で使用することも、AutoExecute がサポートしていないネットワークリクエスト、ペイロードにカスタムトークンの配置が必要なリクエスト、AutoExecute への増分移行中に AutoExecute と組み合わせて使用することもできます。

AutoExecute を構成する

AutoExecute を使用すると、ウェブページ上のネットワークリクエストをインターセプトし、フロントエンドアクションごとに手動で grecaptcha.enterprise.execute() を呼び出す必要がなくなるため、フロントエンド JavaScript の統合を簡素化できます。

AutoExecute の仕組み

Fraud Defense スクリプトは、ユニバーサルキーのポリシー構成で定義されたネットワークアクションと自動的に統合されます。スクリプトが構成済みのパスへの非同期ネットワークリクエストを検出すると、リクエストをインターセプトしてリスク評価をトリガーし、元のリクエストが続行される前に CAPTCHA チャレンジをユーザーに表示する可能性があります。生成されたレスポンストークンは、リクエストの X-Recaptcha-Token ヘッダーに自動的に追加されます。

サポートされているネットワーク API

AutoExecute は、次の API（これらに依存する AJAX などのフレームワークを含む）によって開始された非同期ネットワークリクエストのみをインターセプトします。

API 名	タイムアウトの構成	実装例
Fetch API	`AbortSignal` コントローラを使用してタイムアウトを設定します。	`AbortSignal.timeout(n)`
XMLHttpRequest	ネイティブの `.timeout` プロパティを使用してタイムアウトを設定します。	`xhr.timeout = n`

統合のおすすめの方法

ユーザーがトリガーしたアクションのみ: AutoExecute は、ページの読み込み中に自動的に読み込まれるリソースをサポートしていません。統合エラーを回避するには、明示的なユーザー操作（ログインボタンや送信ボタンのクリックなど）によってトリガーされるリクエストにのみ AutoExecute を適用します。
レイテンシタイムアウトを防ぐ: Fraud Defense のチャレンジフローによって、ネットワーク遅延が発生することがあります。クライアントサイドのタイムアウトを回避するには、表に記載されているメカニズムを使用して、明示的なリクエストタイムアウトを直接構成します。
機密性の高いパスのみを保護する: 機密性の高いパスにのみ protectedEndpoints を指定し、action パラメータでユーザーインタラクションに意味のある名前を使用します。すべてのエンドポイントを保護することは避けてください。すべてのバックエンドリクエストで Fraud Defense をトリガーすると、パフォーマンスに悪影響を及ぼす可能性があります。詳しいガイダンスについては、アクションをご覧ください。

ウェブページにスクリプトタグを追加する

ウェブページに Fraud Defense を読み込むには、ウェブページの <head></head> 要素内にユニバーサルキーを使用して JavaScript API を追加します。

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Fraud Defense は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、次のように指定します。

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

サポートされている言語については、Fraud Defense の言語コードをご覧ください。

保護されたエンドポイントを構成する

ユニバーサルキーの保護されたエンドポイントを構成するには、タブを選択します。

コンソール

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

[Fraud Defense] に移動
コンソールのツールバーで、リソースセレクタにプロジェクトが表示されていることを確認します。表示されていない場合は、リソースセレクタをクリックしてプロジェクトを選択します。
[キー] タブを選択します。

[キー] タブには、[カード] ビューと [テーブル] ビューの 2 つのビューがあります。プロジェクトにキーが多数ある場合は、[テーブル] ビューのみを使用できます。
[reCAPTCHA キー] セクションで、構成するユニバーサルキーを見つけます。
- [カード] ビューで、キーカードの [キーの詳細] をクリックします。
- [テーブル] ビューで、鍵の名前をクリックします。
[鍵の詳細] ページで、[統合] タブをクリックします。
[ウェブサイトに reCAPTCHA を追加する] ステップで、[自動実行（推奨）] タブを選択します。

省略可: 特定のエンドポイントを手動で保護するには、[手動] タブをクリックして grecaptcha.enterprise.execute() コードスニペットを表示します。
[保護されたエンドポイント] セクションで、[エンドポイントを追加] をクリックして、保護する各エンドポイントを構成します。
1. [アクション] フィールドに、ユーザーインタラクションの名前を入力します。たとえば、login、register、add_to_cart です。詳しいガイダンスについては、アクションをご覧ください。
2. [パス] フィールドに、インターセプトする一意の URL パスまたは glob パターンを入力します。たとえば、/login_api、/register_api、/cart_api/add/* です。
3. 省略可: 別のエンドポイントを追加するには、[エンドポイントを追加] をクリックします。
[保存] をクリックして、保護されたエンドポイントを保存します。

構成を保存すると、[保護されたエンドポイント] テーブルの [ステータス] 列に、過去 24 時間に Fraud Defense が各アクションのトラフィックを受信したかどうかが表示されます。エンドポイントが最初にトラフィックを受信してから、トラフィックステータスが更新されるまでに 10 分ほどかかることがあります。

gcloud

ユニバーサルキーの現在のポリシー構成を調べるには、gcloud alpha recaptcha policies describe コマンドを使用します。

gcloud alpha recaptcha policies describe --key=KEY_ID

保護されたエンドポイントでポリシー構成を更新するには、保護されたパスとアクションを定義する YAML ファイル（POLICY.yaml など）を作成します。

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

gcloud alpha recaptcha policies update コマンドを使用して、YAML ファイルで鍵構成を更新します。

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

REST API

REST API を使用して保護されたエンドポイントを定義するようにポリシー構成を更新するには、projects.keys.updatePolicy メソッドを使用します。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID
KEY_ID: ユニバーサルキーの ID

HTTP メソッドと URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings

リクエストの本文（JSON）:

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X PATCH \
     -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/keys/KEY_ID/policy?updateMask=clientSettings"

PowerShell（Windows）

注: 次のコマンドは、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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings" | Select-Object -Expand Content

成功すると、リクエストは更新されたポリシー構成を返します。

保護されたエンドポイントの構文と制限

ユニバーサル鍵ごとに最大 25 個の保護されたエンドポイントを構成できます。各エンドポイントは次の要件を満たす必要があります。

action: アクション名は 1 ～ 100 文字で、英字、数字、スラッシュ（/）、アンダースコア（_）のみを使用する必要があります。
path（大文字と小文字を区別）: パスは次の条件を満たしている必要があります。
- 一意で、/ で始まり、1 ～ 200 文字で、連続するスラッシュ（//）を含まない。
- ワイルドカード以外のセグメントを少なくとも 1 つ含めます。たとえば、/、/*、/**、/*/ は使用できません。
- ワイルドカードはセグメント全体に指定する必要があります。* は単一のセグメントに一致します。たとえば、/api/*/login や /api/* は有効です。/api/login* は無効です。** は、最後のセグメントとしてのみ複数のセグメントに一致します。たとえば、/api/** は有効ですが、/api/**/login は無効です。

パスマッチングの動作

AutoExecute は、保護されたエンドポイントを上から順にURL パスのみに対して評価します。宛先ドメイン、スキーム、クエリパラメータは無視されます。この動作には、次のような実用的な影響があります。

パスの一致順序: AutoExecute は、最初に一致したエンドポイントを適用します。一致するエンドポイントがない場合、AutoExecute はリクエストをインターセプトしません。より具体的なルートがシャドーイングされないように、ワイルドカードパターンの前に特定のパスを配置します。たとえば、/*/login の前に /mysite/login を指定します。
サードパーティのリクエスト: ページで実行されているサードパーティツール（アナリティクスやパートナースクリプトなど）が、保護されたエンドポイントに一致するパス（/login に一致する https://analytics.example.net/login など）にリクエストを送信すると、AutoExecute はそれらもインターセプトします。これにより、ネットワークレイテンシの増加、指標の歪み、予期しない CAPTCHA チャレンジが発生する可能性があります。競合を回避するには、保護されたパスが固有であることを確認します（例: /auth/v1/login）。パスの競合が発生した場合は、手動インストールを使用します。
クロスドメイン API: バックエンド API がウェブサイトとは異なるドメイン（cdn.example.com と www.example.com など）でホストされている場合、AutoExecute は追加のドメイン構成なしで自動的に動作します。

特定の宛先ドメインとの照合が統合に重要な場合は、機能リクエストを提出してください。

バックエンドでトークンを検証する

バックエンドで、X-Recaptcha-Token リクエストヘッダーからレスポンストークンを取得し、2 分以内に評価を作成します。

手動インストール

検証が必要なユーザー操作に Fraud Defense による確認を追加することをおすすめします。たとえば、フォームの送信アクションを検証する場合は、送信アクションに Fraud Defense による確認を追加する必要があります。

Fraud Defense の検証を追加する場所に応じて、適切なオプションを選択します。

ユーザーの操作に関する確認を追加する
HTML ボタンに Fraud Defense を追加する

ユーザーの操作に関する確認を追加する

ウェブページに reCAPTCHA を読み込むには、ユニバーサルキーを使用して JavaScript API をウェブページの <head></head> 要素内に追加します。
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、次のように指定します。

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

サポートされている言語については、Fraud Defense の言語コードをご覧ください。

バッジの場所を指定する場合は、スクリプトタグのクエリパラメータとして badge=LOCATION を使用します。例: https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleftデフォルトの場所は bottomright に設定されています。他に、inline や bottomleft の値になることがあります。
ユーザー操作に Fraud Defense の検証を追加する手順は次のとおりです。
1. Fraud Defense ライブラリの読み込み後に grecaptcha.enterprise.execute() が実行されるようにするには、grecaptcha.enterprise.ready() を使用します。
2. ユニバーサルキーを使用して、保護対象のインタラクションごとに grecaptcha.enterprise.execute() を呼び出します。action パラメータで、ユーザーインタラクションに意味のある名前を指定します。詳しいガイダンスについては、アクションをご覧ください。
  
  ヒント: execute 呼び出しを、LOGIN、SIGNUP、PASSWORD_RESET、PURCHASE などの機密性の高いアクションに追加します。
  次の例では、ログインアクションで grecaptcha.enterprise.execute() を呼び出す方法を示します。
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>
```
トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

重要: バックエンドは、CreateAssessmentRequest で assessment.event.expected_action（JSON では expectedAction）を指定する必要があります。これは、execute() 呼び出しで構成されたアクションと一致している必要があります。たとえば、フロントエンドアクションを LOGIN に構成する場合、バックエンドは、そのリクエストの評価を作成するときに expected_action を LOGIN に設定する必要があります。不一致が存在する場合は、攻撃者が操作を偽装しようとしていることを示しています。

HTML ボタンに Fraud Defense を追加する

ウェブページに reCAPTCHA を読み込むには、ユニバーサルキーを使用して JavaScript API をウェブページの <head></head> 要素内に追加します。
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense は、デフォルトでブラウザの言語を使用します。別の言語を指定する場合は、スクリプトで hl=LANG 属性を使用します。たとえば、フランス語を使用するには、次のように指定します。

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

サポートされている言語については、Fraud Defense の言語コードをご覧ください。
HTML ボタンに Fraud Defense を追加する手順は次のとおりです。
1. トークンを処理するコールバック関数を定義します。
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
  詳細については、requestSubmit() メソッドをご覧ください。
2. HTML ボタンに属性を追加します。
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
  バッジの場所を指定する場合は、class="g-recaptcha" を含む要素で data-badge="LOCATION" 属性を使用します。デフォルトの場所は bottomright に設定されています。他に、inline や bottomleft の値になることがあります。
3. サイトでのフォームの送信にこのボタンを使用すると、g-recaptcha-response POST パラメータにレスポンストークンが含まれます。
  
  注: g-recaptcha ボタンを disabled として設定する場合、Fraud Defense が読み込まれるときにボタンが有効になります。
トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

重要: バックエンドは、CreateAssessmentRequest で assessment.event.expected_action（JSON では expectedAction）を指定する必要があります。これは、ボタンに設定されたアクションと一致する必要があります。たとえば、ボタンのアクションを submit に構成する場合、バックエンドは、そのリクエストの評価を作成するときに expected_action を submit に設定する必要があります。不一致が存在する場合は、攻撃者が操作を偽装しようとしていることを示しています。

次のステップ

カスタムルールに基づいて CAPTCHA チャレンジをトリガーするには、チャレンジポリシーを構成します。
reCAPTCHA レスポンストークンを評価するため、評価を作成する。