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

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

このドキュメントでは、Universal キーをインストールしてウェブページに統合する方法について説明します。

始める前に

Google Cloud Fraud Defense の環境を準備する。
ユニバーサルキーを作成し、ドメインを構成します。

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

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

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

統合方法に応じて、適切なオプションを選択します。

AutoExecute の構成

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

AutoExecute は、Fetch API または XMLHttpRequest で開始された非同期ネットワークリクエストのみをインターセプトします。これには、これらの API を使用する AJAX などのフレームワークからのリクエストも含まれます。
AutoExecute は、ページの読み込み時に自動的に読み込まれるリソースではサポートされていません。代わりに、ログインボタンなど、ページ上のユーザー操作によってトリガーされるネットワークリクエストに AutoExecute を適用します。
Fraud Defense のチャレンジによってネットワークタイムアウトが発生しないようにするには、リクエストにタイムアウトを直接適用します。Fetch API には AbortSignal.timeout(n) を使用し、XMLHttpRequest には XMLHttpRequest.timeout プロパティを使用します。

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

ウェブページに Fraud Defense を読み込むには、ユニバーサルキーを使用して 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 の言語コードをご覧ください。

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

Fraud Defense スクリプトは、ユニバーサルキーのポリシー構成で定義されたネットワークアクションと自動的に統合されます。このセクションでは、URL パス（path）とアクション名（action）のマッピングを定義します。

Fraud Defense スクリプトがマッピングされたパスへの非同期ネットワークリクエストを検出すると、リクエストをインターセプトしてリスク評価をトリガーし、元のリクエストが続行される前に CAPTCHA チャレンジをユーザーに表示することがあります。生成されたレスポンストークンは、リクエストの X-Recaptcha-Token ヘッダーに自動的に追加されます。

gcloud

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

gcloud alpha recaptcha policies describe --key=KEY_ID

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

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - 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.protectedEndpointGroup

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

{
"clientSettings": {
  "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.protectedEndpointGroup"

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.protectedEndpointGroup" | Select-Object -Expand Content

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

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

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

サードパーティのリクエスト: ページで実行されているサードパーティツール（アナリティクスやパートナースクリプトなど）が、保護されたエンドポイントに一致するパス（/login に一致する https://analytics.example.net/login など）にリクエストを送信すると、AutoExecute はそれらもインターセプトします。これにより、ネットワークレイテンシの増加、指標の歪み、予期しない CAPTCHA チャレンジが発生する可能性があります。競合を回避するには、保護されたパスが固有であることを確認します（例: /auth/v1/login）。パスの競合が発生した場合は、手動インストールを使用します。
クロスドメイン API: バックエンド API がウェブサイトとは異なるドメイン（examplecdn.net と 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() メソッドをご覧ください。
1. 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 の値になることがあります。
1. サイトでのフォームの送信にこのボタンを使用すると、g-recaptcha-response POST パラメータにレスポンストークンが含まれます。
注: g-recaptcha ボタンを disabled として設定する場合、Fraud Defense が読み込まれるときにボタンが有効になります。
トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

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

次のステップ

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