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.
Rufen Sie in der Cloud Console die Seite reCAPTCHA Enterprise API auf.
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.
Klicken Sie auf Aktivieren.
reCAPTCHA-Seite zur Identitätsbestätigung implementieren
So implementieren Sie eine reCAPTCHA-Seite:
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
odersession-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
oderINVISIBLE
.Geben Sie Folgendes an:
INVISIBLE
für Websiteschlüssel der Identitätsbestätigung.SCORE
oderCHECKBOX
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 ContentSie 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" } }
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:
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
oderCHECKBOX
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
odersession-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
oderINVISIBLE
.Geben Sie Folgendes an:
INVISIBLE
für Websiteschlüssel der Identitätsbestätigung.SCORE
oderCHECKBOX
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 ContentSie 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" } }
Installieren Sie auf Ihren Webseiten den Aktionstoken-Websiteschlüssel. Eine Anleitung finden Sie in dem Dokument, das dem Integrationstyp Ihres Aktionstoken-Websiteschlüssels entspricht.
- Informationen zum Integrationstyp
SCORE
finden Sie unter Websiteschlüssel in das Front-End integrieren. - Informationen zum
CHECKBOX
-Integrationstyp finden Sie unter Das reCAPTCHA-Widget im Front-End rendern.
- Informationen zum Integrationstyp
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> ```
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:
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
odersession-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
oderINVISIBLE
.Geben Sie Folgendes an:
INVISIBLE
für Websiteschlüssel der Identitätsbestätigung.SCORE
oderCHECKBOX
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 ContentSie 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" } }
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>
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>