reCAPTCHA Enterprise für WAF und Google Cloud Armor implementieren

In diesem Dokument wird beschrieben, wie Sie eine reCAPTCHA-Herausforderungsseite, reCAPTCHA-Aktions-Tokens und reCAPTCHA-Sitzungstokens für Google Cloud Armor implementieren.

Hinweis

Bevor Sie eine reCAPTCHA-Aufgabeseite, Aktions- oder Sitzungstokens verwenden, aktivieren Sie die reCAPTCHA Enterprise API.

  1. Rufen Sie in der Cloud Console die Seite reCAPTCHA Enterprise API auf.

    Zur reCAPTCHA Enterprise API

  2. Prüfen Sie, ob der Name Ihres Projekts in der Projektauswahl oben auf der Seite angezeigt wird. Wenn Sie den Namen Ihres Projekts nicht sehen, klicken Sie auf die Projektauswahl und wählen Sie Ihr Projekt aus.

  3. Klicken Sie auf Aktivieren.

reCAPTCHA-Seite zur Identitätsbestätigung implementieren

So implementieren Sie eine reCAPTCHA-Seite:

  1. Erstellen Sie mit dem Befehl gcloud recaptcha create create einen reCAPTCHA-Websiteschlüssel für die reCAPTCHA-Wiederherstellung:

    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
      

    Geben Sie folgende Werte an:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.
    • WAF_FEATURE: Name der WAF-Funktion. Geben Sie challenge-page an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Google Cloud Armor an.
    • INTEGRATION_TYPE: Art der Integration. Geben Sie INVISIBLE an.
    • DOMAINS: Domains oder Subdomains von Websites, die den Schlüssel verwenden dürfen. Geben Sie --allow-all-domains für WAF-Websiteschlüssel an, um die Domainbestätigung zu deaktivieren.

    REST UND BEFEHLSZEILE

    API-Referenzinformationen zu Schlüsseltypen und Integrationstypen finden Sie unter Schlüssel und Integrationstyp.

    Bevor Sie eine der Anfragedaten verwenden, nehmen Sie folgende Ersetzungen vor:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • DISPLAY_NAME: Anzeigename für den Schlüssel.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.
    • WAF_FEATURE: Name der WAF-Funktion. Geben Sie challenge-page, action-token oder session-token an.
    • DOMAINS: Domains oder Subdomains von Websites, die den Schlüssel verwenden dürfen. Geben Sie --allow-all-domains an, um die Dominam-Überprüfung zu deaktivieren.
    • TYPE_OF_INTEGRATION: SCORE, CHECKBOX oder INVISIBLE.

      Geben Sie Folgendes an:

      • INVISIBLE für Websiteschlüssel der Identitätsbestätigung.
      • SCORE oder CHECKBOX für Websitetoken-Aktionstokens.
      • SCORE für Sitzungstoken-Websiteschlüssel.

    HTTP-Methode und URL:

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

    JSON-Text der Anfrage:

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

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    $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

    Sie sollten in etwa folgende JSON-Antwort erhalten:

    {
        "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-Sicherheitsrichtlinien konfigurieren Informationen zum Verwenden eines reCAPTCHA-seitigen Websiteschlüssels mit Ihrer Sicherheitsrichtlinie finden Sie unter Regeln für die Bot-Verwaltung konfigurieren.

reCAPTCHA-Aktionstokens implementieren

reCAPTCHA Enterprise muss auf Ihren Webseiten ausgeführt werden, um Aktionstokens zu generieren. Nachdem reCAPTCHA Enterprise ein Aktionstoken generiert hat, hängen Sie das Token an einen vordefinierten Anfrageheader an, wo Sie Nutzeraktionen wie den Checkout schützen müssen. Aktionstokens sind standardmäßig 30 Minuten lang gültig und können kürzer sein. Daher müssen Sie das Aktionstoken vor dem Ablauf des Tokens an einen vordefinierten Anfrageheader anhängen, damit Google Cloud Armor die Tokenattribute auswerten kann.

So implementieren Sie ein reCAPTCHA-Aktionstoken:

  1. Erstellen Sie mit dem Befehl gcloud recaptcha key create einen reCAPTCHA-WAF-Token für den Aktionstoken:

    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
      

    Geben Sie folgende Werte an:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.
    • WAF_FEATURE: Name der WAF-Funktion. Geben Sie action-token an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Google Cloud Armor an.
    • INTEGRATION_TYPE: Art der Integration. Geben Sie SCORE oder CHECKBOX an.
    • DOMAINS: Domains oder Subdomains von Websites, die den Schlüssel verwenden dürfen. Geben Sie --allow-all-domains für WAF-Websiteschlüssel an, um die Domainbestätigung zu deaktivieren.

    REST UND BEFEHLSZEILE

    API-Referenzinformationen zu Schlüsseltypen und Integrationstypen finden Sie unter Schlüssel und Integrationstyp.

    Bevor Sie eine der Anfragedaten verwenden, nehmen Sie folgende Ersetzungen vor:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • DISPLAY_NAME: Anzeigename für den Schlüssel.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.
    • WAF_FEATURE: Name der WAF-Funktion. Geben Sie challenge-page, action-token oder session-token an.
    • DOMAINS: Domains oder Subdomains von Websites, die den Schlüssel verwenden dürfen. Geben Sie --allow-all-domains an, um die Dominam-Überprüfung zu deaktivieren.
    • TYPE_OF_INTEGRATION: SCORE, CHECKBOX oder INVISIBLE.

      Geben Sie Folgendes an:

      • INVISIBLE für Websiteschlüssel der Identitätsbestätigung.
      • SCORE oder CHECKBOX für Websitetoken-Aktionstokens.
      • SCORE für Sitzungstoken-Websiteschlüssel.

    HTTP-Methode und URL:

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

    JSON-Text der Anfrage:

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

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    $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

    Sie sollten in etwa folgende JSON-Antwort erhalten:

    {
        "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. Installieren Sie auf Ihren Webseiten den Aktionstoken-Websiteschlüssel. Eine Anleitung finden Sie in dem Dokument, das dem Integrationstyp Ihres Aktionstoken-Websiteschlüssels entspricht.

  3. Nachdem Sie das Token von reCAPTCHA Enterprise erhalten haben, hängen Sie es an einen vordefinierten Anfrageheader im folgenden Format an:

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

    Sie können Sprachen wie XHR, Ajax oder Fetch API verwenden, um das Token an einen vordefinierten Anfrageheader anzuhängen.

    Das folgende Beispielskript zeigt, wie die Ausführungsaktion geschützt und das Token mithilfe von JavaScript + XHR an einen vordefinierten Anfrage-Header angehängt wird:

       <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-Sicherheitsrichtlinien konfigurieren Informationen zum Verwenden des reCAPTCHA-Action-Token-Websiteschlüssels mit Ihrer Sicherheitsrichtlinie finden Sie unter Regeln für die Bot-Verwaltung konfigurieren.

reCAPTCHA-Sitzungstokens implementieren

Das reCAPTCHA-JavaScript legt nach der Bewertung ein reCAPTCHA-Sitzungstoken als Cookie im Browser des Endnutzers fest. Der Browser des Endnutzers hängt das Cookie an und aktualisiert das Cookie, solange das reCAPTCHA-JavaScript aktiv bleibt.

Um ein Sitzungs-Token als Cookie bereitzustellen, installieren Sie einen auf einem reCAPTCHA-Wert basierenden Websiteschlüssel auf mindestens einer Ihrer Webseiten, die die folgenden Anforderungen erfüllen:

  • Die Webseite muss die Seite sein, die der Endnutzer aufruft, bevor die Seite geschützt werden muss. Wenn Sie beispielsweise die Kassenseite schützen möchten, installieren Sie den auf dem reCAPTCHA-Score basierenden Websiteschlüssel auf der Startseite oder der Produktseite.
  • Die Webseite wird durch eine Google Cloud Armor-Sicherheitsrichtlinie geschützt.

Mit diesem Cookie können Sie nachfolgende Anfragen des Nutzers und das Laden der Seite in einer bestimmten Domain schützen. Sitzungstokens sind standardmäßig 30 Minuten lang gültig. Wenn der Nutzer jedoch auf der Seite verbleibt, auf der Sie das Sitzungstoken implementiert haben, aktualisiert reCAPTCHA Enterprise das Sitzungstoken regelmäßig, um zu verhindern, dass es abläuft.

Installieren Sie Sitzungs-Tokens auf jeder Seite, die durch reCAPTCHA Enterprise geschützt werden muss. Wir empfehlen, reCAPTCHA Enterprise auf jeder Seite zu installieren und Google Cloud Armor-Regeln zu verwenden, um den Zugriff auf allen Seiten zu erzwingen, mit Ausnahme der ersten Seite, die Endnutzer durchsuchen.

Hier ist ein Beispiel für ein reCAPTCHA-Sitzungstoken:

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

So implementieren Sie ein reCAPTCHA-Sitzungstoken:

  1. Erstellen Sie mit dem Befehl gcloud recaptcha keys create einen reCAPTCHA WAW-Sitzungstoken-Websiteschlüssel:

    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
      

    Geben Sie folgende Werte an:

    • DISPLAY_NAME: Name für den Schlüssel. In der Regel ein Websitename.
    • WAF_FEATURE: Name der WAF-Funktion. Geben Sie session-token an.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Google Cloud Armor an.
    • INTEGRATION_TYPE: Art der Integration. Geben Sie SCORE an.
    • DOMAINS: Domains oder Subdomains von Websites, die den Schlüssel verwenden dürfen. Geben Sie --allow-all-domains für WAF-Websiteschlüssel an, um die Domainbestätigung zu deaktivieren.

    REST UND BEFEHLSZEILE

    API-Referenzinformationen zu Schlüsseltypen und Integrationstypen finden Sie unter Schlüssel und Integrationstyp.

    Bevor Sie eine der Anfragedaten verwenden, nehmen Sie folgende Ersetzungen vor:

    • PROJECT_ID ist Ihre Google Cloud-Projekt-ID.
    • DISPLAY_NAME: Anzeigename für den Schlüssel.
    • WAF_SERVICE: Name des WAF-Dienstanbieters. Geben Sie CA für Cloud Armor an.
    • WAF_FEATURE: Name der WAF-Funktion. Geben Sie challenge-page, action-token oder session-token an.
    • DOMAINS: Domains oder Subdomains von Websites, die den Schlüssel verwenden dürfen. Geben Sie --allow-all-domains an, um die Dominam-Überprüfung zu deaktivieren.
    • TYPE_OF_INTEGRATION: SCORE, CHECKBOX oder INVISIBLE.

      Geben Sie Folgendes an:

      • INVISIBLE für Websiteschlüssel der Identitätsbestätigung.
      • SCORE oder CHECKBOX für Websitetoken-Aktionstokens.
      • SCORE für Sitzungstoken-Websiteschlüssel.

    HTTP-Methode und URL:

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

    JSON-Text der Anfrage:

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

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    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

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

    $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

    Sie sollten in etwa folgende JSON-Antwort erhalten:

    {
        "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. Fügen Sie dem reCAPTCHA-JavaScript den Sitzungsschlüssel der Sitzung und waf=session hinzu.

    Das folgende Beispielskript zeigt, wie ein Sitzungs-Token auf einer Webseite implementiert wird:

      <!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-Sicherheitsrichtlinien konfigurieren Informationen zum Verwenden des reCAPTCHA-Sitzungstokens-Websiteschlüssels mit Ihrer Sicherheitsrichtlinie finden Sie unter Regeln für die Botverwaltung konfigurieren.

Beispiele für die Verwendung mehrerer Features in einer einzelnen Anwendung

Sie können ein oder mehrere reCAPTCHA Enterprise für WAF-Funktionen in einer einzelnen Anwendung verwenden.

Beispiel 1: reCAPTCHA-Sitzungstokens und reCAPTCHA-Abfrageseite verwenden

Sie können auf Seiten, auf die ein Nutzer zugreifen kann, ein reCAPTCHA-Sitzungstoken hinzufügen, damit das Cookie regelmäßig aktualisiert wird, z. B. eine Anmeldeseite. Konfigurieren Sie die Regel der Google Cloud Armor-Sicherheitsrichtlinie so, dass die Anfrage bei einer niedrigen Punktzahl auf eine reCAPTCHA-Aufgabeseite weitergeleitet wird.

Die folgende Abbildung zeigt einen Workflow, der Features der reCAPTCHA-Sitzungstoken- und reCAPTCHA-Herausforderung verwendet:

Beispiel 2: reCAPTCHA-Aktionstokens und reCAPTCHA-Abfrageseite verwenden

Sie können ein reCAPTCHA-Aktionstoken hinzufügen, um eine Nutzeraktion zu schützen, z. B. Checkout. Konfigurieren Sie die Regel der Google Cloud Armor-Sicherheitsrichtlinie so, dass die Anfrage in einer der folgenden Bedingungen an eine reCAPTCHA-Herausforderung weitergeleitet wird:

  • Die Punktzahl ist niedrig.
  • Das Attribut action_name des Aktionstokens stimmt nicht mit der geschützten Nutzeraktion überein.

Die folgende Abbildung zeigt einen Workflow, der Features der reCAPTCHA-Aktions- und reCAPTCHA-Herausforderung verwendet:

Das folgende Beispielskript zeigt, wie Sie ein reCAPTCHA-Aktions-Token verwenden und auf eine reCAPTCHA-Aufgabeseite mit dem angehängten Aktion-Token weiterleiten:

   <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>

Weitere Informationen