Universelle Schlüssel auf Webseiten installieren

Ein universeller Fraud Defense-Schlüssel schützt Ihre Webanwendungen und API-Endpunkte vor automatisierten Bot-Angriffen, Missbrauch von Anmeldedaten und Betrug. Mit einem universellen Schlüssel können Sie Schutzmaßnahmen auf Ihrer Website mit automatischer Abfangung von Netzwerkanfragen (AutoExecute), manueller JavaScript-Ausführung oder einer Kombination aus beiden Methoden bereitstellen.

Hinweis

  1. Umgebung für Google Cloud Fraud Defense vorbereiten

  2. Universalschlüssel erstellen

  3. Konfigurieren Sie Domains für Ihren Universalschlüssel.

  4. Wenn Sie die Spalte Status für geschützte Endpunkte in derGoogle Cloud Console aufrufen möchten, benötigen Sie die Cloud Monitoring-Berechtigung monitoring.timeSeries.list. Diese Berechtigung ist in den vordefinierten Fraud Defense-Rollen enthalten: reCAPTCHA Enterprise Admin, reCAPTCHA Enterprise Editor und reCAPTCHA Enterprise Viewer.

Universelle Schlüssel auf Ihrer Website installieren

Wenn Sie den 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.

AutoExecute konfigurieren

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

Funktionsweise von AutoExecute

Das Fraud Defense-Skript wird automatisch in Netzwerkaktionen eingebunden, die in der Richtlinienkonfiguration Ihres Universalschlüssels definiert sind. Wenn das Script eine asynchrone Netzwerkanfrage an einen konfigurierten Pfad erkennt, fängt es die Anfrage ab, löst eine Risikobewertung aus und zeigt dem Nutzer möglicherweise eine CAPTCHA-Eingabe an, bevor die ursprüngliche Anfrage fortgesetzt wird. Das generierte Antworttoken wird automatisch an den X-Recaptcha-Token-Header in der Anfrage angehängt.

Unterstützte Netzwerk-APIs

AutoExecute fängt nur asynchrone Netzwerkanfragen ab, die von den folgenden APIs (einschließlich Frameworks wie AJAX, die darauf basieren) initiiert werden:

API-Name Konfiguration des Zeitlimits Implementierungsbeispiel
Fetch API Legen Sie Zeitlimits mit dem AbortSignal-Controller fest. AbortSignal.timeout(n)
XMLHttpRequest Legen Sie Zeitlimits mit dem nativen Attribut .timeout fest. xhr.timeout = n

Best Practices für die Integration

  • Nur vom Nutzer ausgelöste Aktionen: AutoExecute unterstützt keine Ressourcen, die beim Seitenaufbau automatisch geladen werden. Um Integrationsfehler zu vermeiden, wenden Sie „AutoExecute“ nur auf Anfragen an, die durch explizite Nutzerinteraktionen ausgelöst werden (z. B. Klicken auf eine Anmelde- oder Senden-Schaltfläche).
  • Latenzzeitüberschreitungen verhindern: Fraud Defense-Challenge-Abläufe können gelegentlich zu Netzwerkverzögerungen führen. Um clientseitige Zeitüberschreitungen zu vermeiden, sollten Sie explizite Zeitüberschreitungen für Anfragen immer direkt mit den in der Tabelle aufgeführten Mechanismen konfigurieren.
  • Nur sensible Pfade schützen: Geben Sie protectedEndpoints nur für sensible Pfade an und verwenden Sie im Parameter action einen aussagekräftigen Namen für die Nutzerinteraktion. Vermeiden Sie es, jeden Endpunkt zu schützen, da das Auslösen von Fraud Defense bei jeder Backend-Anfrage die Leistung beeinträchtigen kann. Weitere Informationen finden Sie unter Aktionen.

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 Universalschlü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.

Geschützte Endpunkte konfigurieren

Wählen Sie einen Tab aus, um geschützte Endpunkte für Ihren Universalschlüssel zu konfigurieren:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Fraud Defense auf.

    Zu Fraud Defense

  2. Prüfen Sie in der Symbolleiste der Console, ob Ihr Projekt in der Ressourcenauswahl angezeigt wird. Wenn nicht, klicken Sie auf die Ressourcenauswahl und wählen Sie Ihr Projekt aus.

  3. Wählen Sie den Tab Keys aus.

    Der Tab Schlüssel hat zwei Ansichten: Karten und Tabelle. Wenn Ihr Projekt viele Schlüssel enthält, ist nur die Ansicht Tabelle verfügbar.

  4. Suchen Sie im Abschnitt reCAPTCHA-Schlüssel den universellen Schlüssel, den Sie konfigurieren möchten:

    • Klicken Sie in der Ansicht Karten auf der Schlüsselkarte auf Schlüsseldetails.
    • Klicken Sie in der Ansicht Tabelle auf den Namen des Schlüssels.

  5. Klicken Sie auf der Seite Schlüsseldetails auf den Tab Integration.

  6. Wählen Sie im Schritt reCAPTCHA auf Ihrer Website hinzufügen den Tab AutoExecute (empfohlen) aus.

    Optional: Wenn Sie bestimmte Endpunkte manuell schützen möchten, klicken Sie auf den Tab Manuell, um das grecaptcha.enterprise.execute()-Code-Snippet aufzurufen.

  7. Klicken Sie im Abschnitt Geschützte Endpunkte auf Endpunkt hinzufügen, um jeden Endpunkt zu konfigurieren, den Sie schützen möchten:

    1. Geben Sie im Feld Aktion einen Namen für die Nutzerinteraktion ein. Beispiel: login, register oder add_to_cart. Weitere Informationen finden Sie unter Aktionen.
    2. Geben Sie im Feld Pfad den eindeutigen URL-Pfad oder das Glob-Muster ein, das abgefangen werden soll. Beispiel: /login_api, /register_api oder /cart_api/add/*.
    3. Optional: Klicken Sie auf Endpunkt hinzufügen, um einen weiteren Endpunkt hinzuzufügen.

  8. Klicken Sie auf Speichern, um die geschützten Endpunkte zu speichern.

Nachdem Sie die Konfiguration gespeichert haben, wird in der Spalte Status der Tabelle Geschützte Endpunkte angezeigt, ob Fraud Defense in den letzten 24 Stunden Traffic für die einzelnen Aktionen erhalten hat. Es kann 10 Minuten dauern, bis der Trafficstatus aktualisiert wird, nachdem ein Endpunkt zum ersten Mal Traffic empfangen hat.

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:

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - 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

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 Projekt-ID in Google Cloud
  • 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

JSON-Text anfordern:

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "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:

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

Syntax und Limits für geschützte Endpunkte

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.
    • Fügen Sie mindestens ein Segment hinzu, das kein Platzhalter ist. Beispiel: darf nicht /, /*, /** oder /*/ sein.
    • Platzhalter müssen vollständige Segmente ausfüllen: * entspricht einem einzelnen Segment. /api/*/login oder /api/* sind beispielsweise gültig, /api/login* ist ungültig und ** entspricht mehreren Segmenten nur als letztes Segment. /api/** ist beispielsweise gültig, /api/**/login jedoch nicht.

Verhalten beim Pfadabgleich

AutoExecute wertet geschützte Endpunkte nacheinander von oben nach unten nur anhand des URL-Pfads aus. Die Zieldomain, das Schema und die Suchparameter werden ignoriert. Dieses Verhalten hat die folgenden praktischen Auswirkungen:

  • Reihenfolge des Pfadabgleichs: AutoExecute wendet den ersten übereinstimmenden Endpunkt an. Wenn kein Endpunkt übereinstimmt, wird die Anfrage von AutoExecute nicht abgefangen. Platzieren Sie bestimmte Pfade vor Platzhaltermustern, um zu vermeiden, dass spezifischere Routen verdeckt werden. Führen Sie beispielsweise /mysite/login vor /*/login auf.
  • 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. Um Konflikte zu vermeiden, sollten Sie darauf achten, dass Ihre geschützten Pfade eindeutig sind (z. B. /auth/v1/login). Alternativ können Sie die manuelle Installation verwenden, wenn Pfadkonflikte auftreten.
  • Domainübergreifende APIs: Wenn Ihre Backend-API auf einer anderen Domain als Ihre Website gehostet wird (z. B. cdn.example.com 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.

Tokens im Backend verifizieren

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-Überprüfung für eine Nutzerinteraktion hinzuzufügen, die überprüft 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

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

    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.

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

      Das folgende Beispiel zeigt, 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>

  3. Nachdem das Token generiert wurde, wird das reCAPTCHA-Token an Ihr Backend gesendet und es wird innerhalb von zwei Minuten eine Bewertung erstellt.

Fraud Defense zu einem HTML-Button hinzufügen

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

  2. 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 im Artikel zur Methode requestSubmit().

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

    3. Wenn dieser Button verwendet wird, um ein Formular auf Ihrer Website einzureichen, enthält der POST-Parameter g-recaptcha-response das Antworttoken.

  3. Nachdem das Token generiert wurde, wird das reCAPTCHA-Token an Ihr Backend gesendet und es wird innerhalb von zwei Minuten eine Bewertung erstellt.

Nächste Schritte