WAF と Google Cloud Armor の統合用に reCAPTCHA Enterprise を実装する

このドキュメントでは、Google Cloud Armor の reCAPTCHA 課題ページreCAPTCHA アクション トークンreCAPTCHA セッション トークンを実装する方法について説明します。

始める前に

reCAPTCHA 課題ページ、アクション トークン、またはセッション トークンを使用する前に、reCAPTCHA Enterprise API を有効にします。

  1. Cloud Console で [reCAPTCHA Enterprise API] ページに移動します。

    [reCAPTCHA Enterprise API] に移動

  2. ページの上部にあるプロジェクト セレクタにプロジェクト名が表示されていることを確認します。 プロジェクトの名前が表示されない場合は、プロジェクト セレクタをクリックしてプロジェクトを選択します。

  3. [有効にする] をクリックします。

reCAPTCHA 課題ページを実装する

reCAPTCHA 課題ページを実装するには、次の手順を行います。

  1. gcloud recaptcha keys create コマンドを使用して、reCAPTCHA WAF 課題ページのサイトキーを作成します。

    gcloud

       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    次の値を指定します。

    • DISPLAY_NAME: キーの名前。通常はサイトの名前です。
    • WAF_FEATURE: WAF 機能の名前。challenge-page を実行します。
    • WAF_SERVICE: WAF サービス プロバイダの名前。Google Cloud Armor に CA を指定します。
    • INTEGRATION_TYPE: 統合の種類INVISIBLE を実行します。
    • DOMAINS: キーの使用を許可されたウェブサイトのドメインまたはサブドメインWAF サイトキーの場合は、--allow-all-domains を指定してドメインの所有権確認を無効にします。

    REST とコマンドライン

    キーの種類と統合タイプに関する API リファレンス情報については、統合タイプをご覧ください。

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

    • PROJECT_ID: Google Cloud プロジェクト ID。
    • DISPLAY_NAME: キーの表示名
    • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。
    • WAF_FEATURE: WAF 機能の名前。challenge-page - action-token または session-token を指定します。
    • DOMAINS: キーの使用を許可されたウェブサイトのドメインまたはサブドメインドメイン検証を無効にするには、--allow-all-domains を指定します。
    • TYPE_OF_INTEGRATION: SCORECHECKBOX、または INVISIBLE

      以下を指定します。

      • 課題ページのサイトキーの場合は INVISIBLE
      • アクション トークンのサイト鍵の場合は SCORE または CHECKBOX
      • SCORE: セッション トークンのサイトキー。

    HTTP メソッドと URL:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    JSON 本文のリクエスト:

    
    {
       "displayName": "DISPLAY_NAME",
        'wafSettings': "  {
            "wafService": "WAF_SERVICE",
            "wafFeature": "WAF_FEATURE"
       }
       "webSettings": {
         "allowedDomains": "DOMAINS",
         "integrationType": "TYPE_OF_INTEGRATION"
        }
    }
    

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

    curl

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

    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

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

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

    次のような JSON レスポンスが返されます。

    {
        "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
      "displayName": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
        "integrationType": "SCORE",
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "SESSION_TOKEN"
      }
    }
    

  2. Google Cloud Armor セキュリティ ポリシーを構成するセキュリティ ポリシーで reCAPTCHA 課題ページのサイトキーを使用する方法については、bot 管理ルールを構成するをご覧ください。

reCAPTCHA アクション トークンを実装する

アクション トークンを生成するには、reCAPTCHA Enterprise がウェブページで実行されている必要があります。reCAPTCHA Enterprise がアクション トークンを生成したら、購入手続きなどのユーザー アクションを保護する必要がある場合に、事前定義されたリクエスト ヘッダーにアクション トークンを添付します。デフォルトでは、action-token は 30 分間有効です。それより短くすることもできます。したがって、トークンが期限切れになる前に、アクション トークンを事前定義されたリクエスト ヘッダーに添付して、Google Cloud Armor がトークン属性を評価できるようにする必要があります。

reCAPTCHA アクション トークンを実装するには、次の手順を実行します。

  1. gcloud recaptcha keys create コマンドを使用して、reCAPTCHA WAF アクション トークンのサイトキーを作成します。

    gcloud

       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    次の値を指定します。

    • DISPLAY_NAME: キーの名前。通常はサイトの名前です。
    • WAF_FEATURE: WAF 機能の名前。action-token を実行します。
    • WAF_SERVICE: WAF サービス プロバイダの名前。Google Cloud Armor に CA を指定します。
    • INTEGRATION_TYPE: 統合の種類SCORE - CHECKBOX または を指定します。
    • DOMAINS: キーの使用を許可されたウェブサイトのドメインまたはサブドメインWAF サイトキーの場合は、--allow-all-domains を指定してドメインの所有権確認を無効にします。

    REST とコマンドライン

    キーの種類と統合タイプに関する API リファレンス情報については、統合タイプをご覧ください。

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

    • PROJECT_ID: Google Cloud プロジェクト ID。
    • DISPLAY_NAME: キーの表示名
    • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。
    • WAF_FEATURE: WAF 機能の名前。challenge-page - action-token または session-token を指定します。
    • DOMAINS: キーの使用を許可されたウェブサイトのドメインまたはサブドメインドメイン検証を無効にするには、--allow-all-domains を指定します。
    • TYPE_OF_INTEGRATION: SCORECHECKBOX、または INVISIBLE

      以下を指定します。

      • 課題ページのサイトキーの場合は INVISIBLE
      • アクション トークンのサイト鍵の場合は SCORE または CHECKBOX
      • SCORE: セッション トークンのサイトキー。

    HTTP メソッドと URL:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    JSON 本文のリクエスト:

    
    {
       "displayName": "DISPLAY_NAME",
        'wafSettings': "  {
            "wafService": "WAF_SERVICE",
            "wafFeature": "WAF_FEATURE"
       }
       "webSettings": {
         "allowedDomains": "DOMAINS",
         "integrationType": "TYPE_OF_INTEGRATION"
        }
    }
    

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

    curl

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

    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

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

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

    次のような JSON レスポンスが返されます。

    {
        "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
      "displayName": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
        "integrationType": "SCORE",
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "SESSION_TOKEN"
      }
    }
    

  2. ウェブページに、アクション トークン サイトキーをインストールします。手順については、アクション トークンのサイトキーの統合タイプに対応するドキュメントをご覧ください。

  3. reCAPTCHA Enterprise からトークンを受信したら、次の形式の事前定義されたリクエスト ヘッダーにトークンを添付します。

       X-Recaptcha-Token:value-of-your-action-token
    

    XHR、Ajax、Fetch API などの言語および Fetch API を使用して、事前定義されたリクエスト ヘッダーにトークンを添付できます。

    次のサンプル スクリプトは、実行アクションを保護し、JavaScript + XHR を使用して事前定義されたリクエスト ヘッダーにトークンを添付する方法を示しています。

       <script src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_SITE_KEY"></script>
    
       <script>
    
        function onSuccess(action_token) {
          const xhr = new XMLHttpRequest();
          xhr.open('GET','YOUR_URL', false);
          // Attach the action-token to the predefined request header
          xhr.setRequestHeader("X-Recaptcha-Token", action_token);
          xhr.send(null);
        }
    
        function onError(reason) {
          alert('Response promise rejected: ' + reason);
        }
    
        grecaptcha.enterprise.ready(function () {
          document.getElementById("execute-button").onclick = () => {
            grecaptcha.enterprise.execute('ACTION_TOKEN_SITE_KEY', {
            }).then(onSuccess, onError);
          };
        });
       </script>
    
     ```
    
  4. Google Cloud Armor セキュリティ ポリシーを構成するセキュリティ ポリシーで reCAPTCHA アクション トークンのサイトキーを使用する方法については、bot 管理ルールを構成するをご覧ください。

reCAPTCHA セッション トークンを実装する

reCAPTCHA JavaScript は、評価後にエンドユーザーのブラウザで reCAPTCHA セッション トークンを Cookie として設定します。エンドユーザーのブラウザは Cookie を添付し、reCAPTCHA JavaScript がアクティブである限り、その Cookie を更新します。

セッション トークンを Cookie として提供するには、次の要件を満たす少なくとも 1 つのウェブページに reCAPTCHA スコアベースのサイトキーをインストールします。

  • このウェブページは、保護の必要なページの前にエンドユーザーが参照するページである必要があります。たとえば、購入ページを保護するには、reCAPTCHA スコアベースのサイトキーをホームページまたは商品ページにインストールします。
  • このウェブページは Google Cloud Armor セキュリティ ポリシーで保護されています。

この Cookie を使用すると、ユーザーが以降のリクエストや特定のドメインでのページの読み込みを保護できます。セッション トークンは、デフォルトで 30 分間有効です。ただし、セッション トークンを実装したページにユーザーが滞在している場合、reCAPTCHA Enterprise はセッション トークンを定期的に更新して有効期限が切れないようにします。

reCAPTCHA Enterprise で保護する必要がある各ページにセッション トークンをインストールします。すべてのページに reCAPTCHA Enterprise をインストールし、Google Cloud Armor ルールを使用して、エンドユーザーが最初に閲覧するページを除くすべてのページにアクセス権を付与することをおすすめします。

reCAPTCHA セッション トークンの例を次に示します。

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

reCAPTCHA セッション トークンを実装するには、次の手順を行います。

  1. gcloud recaptcha keys create コマンドを使用して、reCAPTCHA WAF セッション トークンのサイトキーを作成します。

    gcloud

       gcloud recaptcha keys create \
          --web \
          --display-name=DISPLAY_NAME  \
          --waf-feature=WAF_FEATURE \
          --waf-service=WAF_SERVICE \
          --integration-type=INTEGRATION_TYPE \
          --domains=DOMAIN_NAME
      

    次の値を指定します。

    • DISPLAY_NAME: キーの名前。通常はサイトの名前です。
    • WAF_FEATURE: WAF 機能の名前。session-token を実行します。
    • WAF_SERVICE: WAF サービス プロバイダの名前。Google Cloud Armor に CA を指定します。
    • INTEGRATION_TYPE: 統合の種類SCORE を実行します。
    • DOMAINS: キーの使用を許可されたウェブサイトのドメインまたはサブドメインWAF サイトキーの場合は、--allow-all-domains を指定してドメインの所有権確認を無効にします。

    REST とコマンドライン

    キーの種類と統合タイプに関する API リファレンス情報については、統合タイプをご覧ください。

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

    • PROJECT_ID: Google Cloud プロジェクト ID。
    • DISPLAY_NAME: キーの表示名
    • WAF_SERVICE: WAF サービス プロバイダの名前。Cloud Armor に CA を指定します。
    • WAF_FEATURE: WAF 機能の名前。challenge-page - action-token または session-token を指定します。
    • DOMAINS: キーの使用を許可されたウェブサイトのドメインまたはサブドメインドメイン検証を無効にするには、--allow-all-domains を指定します。
    • TYPE_OF_INTEGRATION: SCORECHECKBOX、または INVISIBLE

      以下を指定します。

      • 課題ページのサイトキーの場合は INVISIBLE
      • アクション トークンのサイト鍵の場合は SCORE または CHECKBOX
      • SCORE: セッション トークンのサイトキー。

    HTTP メソッドと URL:

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

    JSON 本文のリクエスト:

    
    {
       "displayName": "DISPLAY_NAME",
        'wafSettings': "  {
            "wafService": "WAF_SERVICE",
            "wafFeature": "WAF_FEATURE"
       }
       "webSettings": {
         "allowedDomains": "DOMAINS",
         "integrationType": "TYPE_OF_INTEGRATION"
        }
    }
    

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

    curl

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

    curl -X POST \
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

    PowerShell

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

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

    次のような JSON レスポンスが返されます。

    {
        "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
      "displayName": "WAF session-token test key",
      "webSettings": {
        "allowAllDomains": true,
        "allowedDomains": [
          "localhost"
        ],
        "integrationType": "SCORE",
      },
      "wafSettings": {
        "wafService": "CA",
        "wafFeature": "SESSION_TOKEN"
      }
    }
    

  2. セッション トークンのサイトキーと waf=session を reCAPTCHA JavaScript に追加します。

    次のサンプル スクリプトは、セッション トークンをウェブページに実装する方法を示しています。

      <!DOCTYPE html>
      <html lang="en">
      <head>
       <meta charset="UTF-8">
       <title>reCAPTCHA WAF Session Token</title>
       <script src="https://www.google.com/recaptcha/enterprise.js?render=SESSION_TOKEN_SITE_KEY&waf=session" async defer></script>
      </head>
    </html>
    
  3. Google Cloud Armor セキュリティ ポリシーを構成するセキュリティ ポリシーで reCAPTCHA セッション トークンのサイトキーを使用する方法については、bot 管理ルールを構成するをご覧ください。

1 つのアプリケーションで複数の機能を使用する例

1 つのアプリケーションで 1 つ以上の WAF 用の reCAPTCHA Enterprise 機能を使用できます。

例 1: reCAPTCHA セッション トークンと reCAPTCHA 課題ページを使用する

ユーザーがアクセスする可能性のあるページ(たとえば ログインページなど)に、reCAPTCHA セッション トークンを追加して、Cookie を定期的に更新できます。スコアが低いときにリクエストを reCAPTCHA 課題ページにリダイレクトするように、Google Cloud Armor セキュリティ ポリシー ルールを構成します。

次の図は、reCAPTCHA セッション トークンと reCAPTCHA 課題ページの機能を使用するワークフローを示しています。

例 2: reCAPTCHA アクション トークンと reCAPTCHA 課題ページを使用する

reCAPTCHA アクション トークンを追加して、ご購入手続きなどのユーザー アクションを保護できます。次のいずれかの状況でリクエストを reCAPTCHA 課題ページにリダイレクトするように、Google Cloud Armor セキュリティ ポリシー ルールを構成します。

  • スコアが低い。
  • アクション トークンの action_name 属性が、保護されているユーザー アクションと一致しない。

次の図は、reCAPTCHA アクション トークンと reCAPTCHA 課題ページの機能を使用するワークフローを示しています。

次のサンプル スクリプトは、reCAPTCHA アクション トークンを使用し、アクション トークンがヘッダーとして添付された reCAPTCHA 課題ページにリダイレクトする方法を示しています。

   <script src="https://www.google.com/recaptcha/enterprise.js?render=ACTION_TOKEN_SITE_KEY"></script>
    <script>
     function onSuccess(token) {
       const xhr = new XMLHttpRequest();
       xhr.open('GET','http://www.abc.com/checkout', false);
       xhr.setRequestHeader("X-Recaptcha-Token", token);
       xhr.onreadystatechange = function() {
         // Make sure that the request is finished and response is ready with 200
         if (this.readyState == 4 && this.status == 200) {
           // Display the response, it could be a reCAPTCHA challenge
           // page based on your Google Cloud Armor security rule settings.
            document.open();
            document.write(xhr.responseText);
            document.close();

         }
       };
       xhr.send(null);
     }

     grecaptcha.enterprise.ready(function () {
       document.getElementById("execute-button").onclick = () => {
         grecaptcha.enterprise.execute('ACTION_TOKEN_SITE_KEY', {
         }).then(onSuccess, onError);
       };
     });
    </script>

次のステップ