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

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

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

始める前に

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

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

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

AutoExecute 構成

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

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

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

ウェブページに 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 がウェブサイトとは異なるドメイン（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>
```
  s
トークンが生成された後、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 レスポンストークンを評価するため、評価を作成する。