Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Universelle Schlüssel auf Webseiten installieren

In diesem Dokument wird beschrieben, wie Sie einen Universalschlüssel installieren und in Ihre Webseiten einbinden können.

Hinweis

Universelle Schlüssel auf Ihrer Website installieren

Wenn Sie Ihren Universalschlüssel installieren und Ihre Webseiten schützen möchten, können Sie die AutoExecute-Konfiguration, die manuelle JavaScript-Installation oder beide Methoden zusammen für verschiedene Endpunkte mit demselben Universalschlüssel verwenden:

AutoExecute-Konfiguration (empfohlen): Fängt asynchrone Netzwerkanfragen an konfigurierte URL-Pfade automatisch ab und hängt das reCAPTCHA-Token an den Anfrageheader an.
Manuelle Installation: Verwendet manuelle grecaptcha.enterprise.execute()-Aufrufe oder HTML-Button-Attribute. Sie können diese Methode allein oder zusammen mit AutoExecute für Netzwerkanfragen verwenden, die von AutoExecute nicht unterstützt werden, für Anfragen, die eine benutzerdefinierte Tokenplatzierung in der Nutzlast erfordern, oder während inkrementeller Migrationen zu AutoExecute.

Wählen Sie je nach Integrationsansatz die entsprechende Option aus:

AutoExecute-Konfiguration

AutoExecute kann die Frontend-JavaScript-Integration vereinfachen, indem Netzwerkanfragen auf Ihren Webseiten abgefangen werden und manuelle grecaptcha.enterprise.execute()-Aufrufe für jede Frontend-Aktion entfallen.

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 automatisch beim Laden der Seite geladen werden, nicht unterstützt. Wenden Sie AutoExecute stattdessen auf Netzwerkanfragen an, die durch Nutzeraktionen auf der Seite ausgelöst werden, z. B. durch einen Anmeldebutton.
Damit Fraud Defense-Aufgaben keine Netzwerk-Zeitüberschreitungen verursachen, wenden Sie Zeitüberschreitungen direkt auf die Anfragen an. Verwenden Sie AbortSignal.timeout(n) für die Fetch API und das Attribut XMLHttpRequest.timeout für XMLHttpRequest.

Script-Tag auf Ihren Webseiten einfügen

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

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

Fraud Defense verwendet standardmäßig die Sprache des Browsers. Wenn Sie eine andere Sprache angeben möchten, verwenden Sie das Attribut hl=LANG in Ihrem Skript. 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-Skript wird automatisch in Netzwerkaktionen eingebunden, die in der Richtlinienkonfiguration Ihres Universalschlüssels definiert sind. In diesem Abschnitt wird eine Zuordnung von URL-Pfaden (path) zu Aktionsnamen (action) definiert.

Wenn das Fraud Defense-Skript 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 Antworttoken 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 Universalschlüssel zu prüfen:

gcloud alpha recaptcha policies describe --key=KEY_ID

Wenn Sie die Richtlinienkonfiguration mit Ihren geschützten Endpunkten aktualisieren möchten, erstellen Sie eine YAML-Datei (z. B. POLICY.yaml), in der Sie die 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. Verwenden Sie dazu den Befehl gcloud alpha recaptcha policies update:

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

REST API

Wenn Sie die Richtlinienkonfiguration aktualisieren möchten, um geschützte Endpunkte mit der REST API zu definieren, verwenden Sie die Methode projects.keys.updatePolicy.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Ihre Google Cloud -Projekt-ID
KEY_ID: die ID Ihres Universalschlü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

Wenn die Anfrage erfolgreich ist, wird die aktualisierte Richtlinienkonfiguration zurückgegeben.

Sie können bis zu 25 geschützte Endpunkte pro Universalschlüssel konfigurieren. Jeder Endpunkt muss die folgenden Anforderungen erfüllen:

action: Der Aktionsname muss 1 bis 100 Zeichen enthalten und darf nur Buchstaben, Zahlen, Schrägstriche (/) und Unterstriche (_) enthalten.
path (Groß-/Kleinschreibung beachten): Der Pfad muss die folgenden Kriterien erfüllen:
- Er muss eindeutig sein, mit / beginnen und 1 bis 200 Zeichen ohne aufeinanderfolgende Schrägstriche (//) enthalten.
- Mindestens ein Segment darf kein Platzhalter sein (z. B. nicht /, /*, /** oder /*/).
- Platzhalter müssen vollständige Segmente ausfüllen: * entspricht einem einzelnen Segment (z. B. sind /api/*/login oder /api/* gültig; /api/login* ist ungültig) und ** entspricht mehreren Segmenten nur als letztes Segment (z. B. ist /api/** gültig; /api/**/login ist ungültig).

Anfragen von Drittanbietern: Wenn Drittanbieter-Tools, 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, das mit /login übereinstimmt), werden diese ebenfalls 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, oder verwenden Sie die manuelle Installation, wenn Pfadkonflikte auftreten.
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 der Abgleich mit bestimmten Zieldomains für Ihre Integration wichtig ist, reichen Sie eine Funktionsanfrage ein.

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

Manuelle Installation

Wir empfehlen, die Fraud Defense-Bestätigung für eine Nutzerinteraktion hinzuzufügen, die bestätigt werden muss. Wenn Sie beispielsweise die Sendeaktion eines Formulars überprüfen möchten, müssen Sie die Fraud Defense-Überprüfung für die Sendeaktion hinzufügen.

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

Bestätigung bei einer Nutzerinteraktion hinzufügen
Fraud Defense zu einem HTML-Button hinzufügen

Bestätigung bei einer Nutzerinteraktion hinzufügen

Wenn Sie reCAPTCHA auf Ihrer Webseite laden möchten, fügen Sie die JavaScript API mit Ihrem universellen Schlüssel im <head></head>-Element Ihrer Webseite hinzu:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense verwendet standardmäßig die Sprache des Browsers. 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 Ort für das Logo angeben möchten, verwenden Sie badge=LOCATION als Suchparameter 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 eine Fraud Defense-Überprüfung hinzu:
1. Damit grecaptcha.enterprise.execute() nach dem Laden der Fraud Defense-Bibliothek ausgeführt wird, verwenden Sie grecaptcha.enterprise.ready().
2. Rufen Sie grecaptcha.enterprise.execute() für jede Interaktion auf, die Sie mit Ihrem Universalschlüssel schützen möchten. 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 Aufruf execute zu sensiblen Aktionen wie LOGIN, SIGNUP, PASSWORD_RESET oder PURCHASE hinzu.
  
  Im folgenden Beispiel wird gezeigt, wie grecaptcha.enterprise.execute() für eine 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>
```
Nachdem das Token generiert wurde, wird das reCAPTCHA-Token an Ihr Backend gesendet und es wird innerhalb von zwei Minuten eine Bewertung erstellt.

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

Fraud Defense zu einem HTML-Button hinzufügen

Wenn Sie reCAPTCHA auf Ihrer Webseite laden möchten, fügen Sie die JavaScript API mit Ihrem universellen Schlüssel im <head></head>-Element Ihrer Webseite hinzu:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense verwendet standardmäßig die Sprache des Browsers. 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 Fraud Defense zu einer HTML-Schaltfläche 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 Logo angeben möchten, verwenden Sie das Attribut data-badge="LOCATION" für das Element mit class="g-recaptcha". Standardmäßig ist der Standort auf bottomright festgelegt. Weitere mögliche Werte sind inline und bottomleft.
1. Wenn dieser Button verwendet wird, um ein Formular auf Ihrer Website einzureichen, 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: Ihr Backend muss assessment.event.expected_action (oder expectedAction in JSON) im CreateAssessmentRequest angeben und es muss mit der auf dem Button konfigurierten Aktion übereinstimmen. Wenn Sie beispielsweise die Schaltflächenaktion als submit konfigurieren, muss Ihr Backend beim Erstellen einer Bewertung für diese Anfrage expected_action auf submit setzen. Wenn es eine Abweichung gibt, bedeutet dies, dass ein Angreifer versucht, Aktionen zu fälschen.

Nächste Schritte

Wenn Sie CAPTCHA-Aufgaben basierend auf benutzerdefinierten Regeln auslösen möchten, konfigurieren Sie Challenge-Richtlinien.
Erstellen Sie eine Bewertung, um das reCAPTCHA-Antworttoken zu bewerten.