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

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

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

始める前に

reCAPTCHA 用に環境を準備します。
ユニバーサルキーを作成してドメインを構成します。

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

ユニバーサルキーをインストールしてウェブページを保護するには、Google Cloud Fraud Defense AutoExecute 構成または標準の JavaScript インストールを選択します。

AutoExecute 構成

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

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

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

ウェブページに 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 の言語コードをご覧ください。

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

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

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

path パラメータは、次のルールで glob パターンをサポートしています。

/ で始まり、空にすることはできません。
バックエンドへのリクエストごとに Fraud Defense をトリガーするとパフォーマンスに悪影響を及ぼす可能性があるため、スタンドアロンの /* または /** にすることはできません。
ワイルドカード *（単一のパスセグメントに一致）と **（複数のパスセグメントに一致）は、パスセグメント全体を占める必要があります（たとえば、 /api/*/login や /api/* は有効ですが、/api/login* は無効です）。
** ワイルドカードは、最後のパスセグメントのみを占める必要があります（たとえば、 /api/** は有効ですが、/api/**/login は無効です）。

サードパーティのリクエスト: ページで実行されているサードパーティツール（分析スクリプトやパートナースクリプトなど）が、保護されたエンドポイントに一致するパスにリクエストを送信する場合（たとえば、 https://analytics.example.net/login が /login に一致する場合）、AutoExecute もそれらをインターセプトします。これにより、ネットワークレイテンシの増加、指標の歪み、予期しない CAPTCHA チャレンジが発生する可能性があります。競合を避けるため、保護されたパスが明確であることを確認します（/auth/v1/login など）。パスの衝突が発生した場合は、標準インストール を使用します。
クロスドメイン API: バックエンド API がウェブサイトとは異なるドメイン（www.example.com と examplecdn.net など）でホストされている場合、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>
```
  s
トークンが生成された後、reCAPTCHA トークンをバックエンドに送信し、2 分以内に評価を作成します。

重要: バックエンドでは、assessment.event.expected_action（JSON の場合は expectedAction）を CreateAssessmentRequest で指定する必要があります。これは、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>
```
バッジの場所を指定する場合は、 data-badge="LOCATION" 属性を要素に使用します。class="g-recaptcha"デフォルトでは、場所は 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 レスポンストークンを評価するため、評価を作成する。