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

Universelle Schlüssel auf Webseiten installieren

In diesem Dokument wird beschrieben, wie Sie einen universellen Schlüssel installieren und in Ihre Webseiten einbinden.

Hinweis

Universelle Schlüssel auf Ihrer Website installieren

Wählen Sie entweder die AutoExecute-Konfiguration von Google Cloud Fraud Defense oder die standardmäßige JavaScript-Installation aus, um Ihren universellen Schlüssel zu installieren und Ihre Webseiten zu schützen:

AutoExecute-Konfiguration

Mit Fraud Defense AutoExecute können Sie die JavaScript-Integration im Frontend vereinfachen, da Netzwerkanfragen auf Ihren Webseiten abgefangen werden. Dadurch ist es nicht mehr erforderlich, grecaptcha.enterprise.execute() für jede Frontend-Aktion manuell aufzurufen.

AutoExecute fängt nur asynchrone Netzwerkanfragen ab, die mit der Fetch API oder XMLHttpRequest initiiert wurden, einschließlich Anfragen von Frameworks wie AJAX, die diese APIs verwenden.
AutoExecute wird für Ressourcen, die beim Laden der Seite automatisch geladen werden, nicht unterstützt. Wenden Sie AutoExecute stattdessen auf Netzwerkanfragen an, die durch Nutzeraktionen auf der Seite ausgelöst werden, z. B. durch eine Anmeldeschaltfläche.
Damit Fraud Defense-Herausforderungen nicht zu Netzwerk-Timeouts führen, wenden Sie Timeouts direkt auf die Anfragen an. Verwenden Sie AbortSignal.timeout(n) für die Fetch API und die XMLHttpRequest.timeout-Eigenschaft für XMLHttpRequest.

Script-Tag auf Ihren Webseiten einfügen

Wenn Sie reCAPTCHA auf Ihre Webseite laden möchten, fügen Sie die JavaScript API mit Ihrem Universal-Schlüssel im <head></head>-Element Ihrer Webseite hinzu:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Bei Fraud Defense wird standardmäßig die Sprache des Browsers verwendet. Wenn Sie eine andere Sprache angeben möchten, verwenden Sie das Attribut hl=LANG in Ihrem Script. Wenn Sie beispielsweise Französisch verwenden möchten, geben Sie Folgendes an:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Informationen zu den unterstützten Sprachen finden Sie unter Sprachcodes für Fraud Defense.

Geschützte Endpunkte konfigurieren

Das Fraud Defense-Script wird automatisch in Netzwerkaktionen eingebunden, die in der Richtlinienkonfiguration Ihres universellen Schlüssels definiert sind. In diesem Abschnitt wird eine Zuordnung von URL-Pfaden (path) zu Aktionsnamen (action) definiert.

Wenn das Fraud Defense-Script eine asynchrone Netzwerkanfrage an einen zugeordneten Pfad erkennt, fängt es die Anfrage ab, löst eine Risikobewertung aus und zeigt dem Nutzer möglicherweise eine CAPTCHA-Aufgabe an, bevor die ursprüngliche Anfrage fortgesetzt wird. Das generierte Antwort-Token wird automatisch an den X-Recaptcha-Token-Header in der Anfrage angehängt.

gcloud

Verwenden Sie den Befehl gcloud alpha recaptcha policies describe, um die aktuelle Richtlinienkonfiguration für Ihren universellen Schlüssel zu prüfen:

gcloud alpha recaptcha policies describe --key=KEY_ID

Um die Richtlinienkonfiguration mit Ihren geschützten Endpunkten zu aktualisieren, erstellen Sie eine YAML-Datei (z. B. POLICY.yaml), in der Sie Ihre geschützten Pfade und Aktionen definieren:

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

Aktualisieren Sie die Schlüsselkonfiguration mit der YAML-Datei mit dem Befehl gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

REST API

Verwenden Sie die Methode projects.keys.updatePolicy, um die Richtlinienkonfiguration zu aktualisieren und geschützte Endpunkte mit der REST API zu definieren.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Ihre Google Cloud Projekt-ID
KEY_ID: die ID Ihres universellen Schlüssels

HTTP-Methode und URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

JSON-Text anfordern:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt haben, die Sie automatisch in der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

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

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)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

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

$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

Bei erfolgreicher Ausführung gibt die Anfrage die aktualisierte Richtlinienkonfiguration zurück.

Der Parameter path unterstützt Glob-Muster mit den folgenden Regeln:

Muss mit / beginnen und darf nicht leer sein.
Darf kein eigenständiges /* oder /** sein, da die Leistung beeinträchtigt werden kann, wenn Fraud Defense bei jeder einzelnen Anfrage an Ihr Backend ausgelöst wird.
Platzhalter * (entspricht einem einzelnen Pfadsegment) und ** (entspricht mehreren Pfadsegmenten) müssen das gesamte Pfadsegment umfassen. /api/*/login oder /api/* sind beispielsweise gültig, /api/login* ist ungültig.
Der Platzhalter ** darf nur das letzte Pfadsegment belegen. Beispiel: /api/** ist gültig, /api/**/login ist ungültig.

Drittanbieteranfragen:Wenn Drittanbietertools, die auf Ihrer Seite ausgeführt werden (z. B. Analyse- oder Partnerskripts), Anfragen an Pfade senden, die mit Ihren geschützten Endpunkten übereinstimmen (z. B. https://analytics.example.net/login, die mit /login übereinstimmt), werden sie auch von AutoExecute abgefangen. Dies kann zu zusätzlicher Netzwerklatenz, verzerrten Messwerten oder unerwarteten CAPTCHA-Abfragen führen. Achten Sie darauf, dass Ihre geschützten Pfade eindeutig sind (z. B. /auth/v1/login), um Konflikte zu vermeiden. Alternativ können Sie die Standardinstallation verwenden, wenn es zu Pfadkollisionen kommt.
Domainübergreifende APIs:Wenn Ihre Backend-API auf einer anderen Domain als Ihre Website gehostet wird (z. B. examplecdn.net im Vergleich zu www.example.com), funktioniert AutoExecute automatisch ohne zusätzliche Domainkonfiguration.

Wenn es für Ihre Integration wichtig ist, dass bestimmte Zieldomains abgeglichen werden, reichen Sie einen Feature Request ein.

Rufen Sie in Ihrem Backend das Antworttoken aus dem X-Recaptcha-Token-Anfrageheader ab und erstellen Sie innerhalb von zwei Minuten eine Bewertung.

Standardinstallation

Wir empfehlen, die Fraud Defense-Überprüfung für eine Nutzerinteraktion hinzuzufügen, die überprüft werden muss. Wenn Sie beispielsweise die Aktion „Senden“ eines Formulars überprüfen möchten, müssen Sie der Aktion „Senden“ die Fraud Defense-Bestätigung hinzufügen.

Wählen Sie je nachdem, wo Sie die Fraud Defense-Überprüfung hinzufügen möchten, die entsprechende Option aus:

Überprüfung für eine Nutzerinteraktion hinzufügen
Fraud Defense auf einem HTML-Button hinzufügen

Überprüfung für eine Nutzerinteraktion hinzufügen

Wenn Sie reCAPTCHA auf Ihre Webseite laden möchten, fügen Sie die JavaScript API mit Ihrem Universal-Schlüssel im <head></head>-Element Ihrer Webseite hinzu:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Bei Fraud Defense wird standardmäßig die Sprache des Browsers verwendet. Wenn Sie eine andere Sprache angeben möchten, verwenden Sie das Attribut hl=LANG in Ihrem Script. Wenn Sie beispielsweise Französisch verwenden möchten, geben Sie Folgendes an:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Informationen zu den unterstützten Sprachen finden Sie unter Sprachcodes für Fraud Defense.

Wenn Sie einen Speicherort für das Logo angeben möchten, verwenden Sie badge=LOCATION als Abfrageparameter im Script-Tag. Beispiel: https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft Standardmäßig ist der Standort auf bottomright festgelegt. Weitere mögliche Werte sind inline und bottomleft.
So fügen Sie einer Nutzerinteraktion die Fraud Defense-Bestätigung hinzu:
1. Verwenden Sie grecaptcha.enterprise.ready(), damit grecaptcha.enterprise.execute() nach dem Laden der Fraud Defense-Bibliothek ausgeführt wird.
2. Rufen Sie bei jeder Interaktion, die Sie mit Ihrem universellen Schlüssel schützen möchten, grecaptcha.enterprise.execute() auf. Geben Sie im Parameter action einen aussagekräftigen Namen für eine Nutzerinteraktion an. Weitere Informationen finden Sie unter Aktionen.
  
  Tipp :Fügen Sie den execute-Aufruf zu sensiblen Aktionen wie LOGIN, SIGNUP, PASSWORD_RESET oder PURCHASE hinzu.
  
  Das folgende Beispiel zeigt, wie grecaptcha.enterprise.execute() bei einer Anmeldeaktion aufgerufen wird:
```
<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
Nachdem das Token generiert wurde, wird das reCAPTCHA-Token an Ihr Backend gesendet und es wird innerhalb von zwei Minuten eine Bewertung erstellt.

Wichtig :In Ihrem Backend muss assessment.event.expected_action (oder expectedAction in JSON) im CreateAssessmentRequest angegeben werden und mit der im execute()-Aufruf konfigurierten Aktion übereinstimmen. Wenn Sie beispielsweise die Frontend-Aktion auf LOGIN konfigurieren, muss Ihr Backend expected_action auf LOGIN setzen, wenn eine Bewertung für diese Anfrage erstellt wird. Wenn es eine Abweichung gibt, bedeutet dies, dass ein Angreifer versucht, Aktionen zu fälschen.

Fraud Defense für einen HTML-Button hinzufügen

Wenn Sie reCAPTCHA auf Ihre Webseite laden möchten, fügen Sie die JavaScript API mit Ihrem Universal-Schlüssel im Element <head></head> Ihrer Webseite hinzu:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Bei Fraud Defense wird standardmäßig die Sprache des Browsers verwendet. Wenn Sie eine andere Sprache angeben möchten, verwenden Sie das Attribut hl=LANG in Ihrem Script. Wenn Sie beispielsweise Französisch verwenden möchten, geben Sie Folgendes an:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Informationen zu den unterstützten Sprachen finden Sie unter Sprachcodes für Fraud Defense.
So fügen Sie einer HTML-Schaltfläche Fraud Defense hinzu:
1. Definieren Sie eine Callback-Funktion, um das Token zu verarbeiten.
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
Weitere Informationen finden Sie unter requestSubmit().
1. Fügen Sie dem HTML-Button Attribute hinzu.
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
Wenn Sie einen Ort für das Symbol angeben möchten, verwenden Sie das Attribut data-badge="LOCATION" für das Element mit class="g-recaptcha". Standardmäßig ist der Speicherort auf bottomright festgelegt. Weitere mögliche Werte sind inline und bottomleft.
1. Wenn dieser Button verwendet wird, um ein Formular auf Ihrer Website zu senden, enthält der POST-Parameter g-recaptcha-response das Antworttoken.
Hinweis: Wenn Sie den Button g-recaptcha als disabled festlegen, wird der Button beim Laden von Fraud Defense aktiviert.
Nachdem das Token generiert wurde, wird das reCAPTCHA-Token an Ihr Backend gesendet und es wird innerhalb von zwei Minuten eine Bewertung erstellt.

Wichtig :In Ihrem Backend muss assessment.event.expected_action (oder expectedAction in JSON) in CreateAssessmentRequest angegeben werden und mit der auf der Schaltfläche konfigurierten Aktion übereinstimmen. Wenn Sie beispielsweise die Schaltflächenaktion auf submit konfigurieren, muss Ihr Backend beim Erstellen einer Bewertung für diese Anfrage expected_action auf submit festlegen. Wenn es eine Abweichung gibt, bedeutet dies, dass ein Angreifer versucht, Aktionen zu fälschen.

Nächste Schritte

Wenn Sie CAPTCHA-Aufgaben anhand benutzerdefinierter Regeln auslösen möchten, konfigurieren Sie Challenge-Richtlinien.
Um das reCAPTCHA-Antworttoken zu bewerten, erstellen Sie eine Bewertung.