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

Aufgabenrichtlinien konfigurieren

In diesem Dokument wird beschrieben, wie Sie Challenge-Richtlinien mit einer vorhandenen Google Cloud Fraud Defense-Integration konfigurieren.

Mit Challenge-Richtlinien können Sie CAPTCHA-Aufgaben basierend auf benutzerdefinierten Regeln selektiv auslösen. Diese Regeln bestimmen, wann eine Fraud Defense-Abfrage angezeigt wird. Dabei werden Risikobewertungen, IP-Adressen, User-Agents, ASNs, geografische Regionen oder verifizierte Bot-Identitäten (KI-Agenten) berücksichtigt.

Sie können Challenge-Richtlinien mit den folgenden empfohlenen Funktionen verwenden:

AutoExecute-Konfiguration: Vereinfacht die JavaScript-Integration für Clientanwendungen.
Challenges: Löst die Nutzerbestätigung aus, wenn dies gemäß Ihren Challenge-Regeln erforderlich ist. Fraud Defense unterstützt die folgenden Arten von Challenges:
- Visuelle Aufgaben: Nutzer werden aufgefordert, Bilder anhand eines Prompts auszuwählen. Standardmäßig wird eine visuelle Aufgabe ausgewählt, wenn eine Regel mit der ausgewählten Aufgabenoption konfiguriert wird.
- Audio-Aufgaben: Nutzer werden aufgefordert, gesprochene Audioinhalte als Alternative für die Barrierefreiheit zu identifizieren.
- QR-Code-Aufgaben: Nutzer werden aufgefordert, einen QR-Code mit ihrem Mobilgerät zu scannen, um eine Aufgabe zu lösen. Ihr Universalschlüssel muss auf einer Zulassungsliste stehen, damit Sie diese Funktion verwenden können. Wenn Sie Ihren Universalschlüssel auf die Zulassungsliste setzen lassen möchten, wenden Sie sich an das Fraud Defense-Team unter fraud-defense@google.com und geben Sie Ihren Universalschlüssel an.

Hinweis

Umgebung für Google Cloud Fraud Defense vorbereiten
Prüfen Sie, ob die Abrechnung für Ihr Google Cloud -Projekt aktiviert ist. Sie können die Abrechnung entweder mit einer Kreditkarte oder einer vorhandenen Google Cloud -Projektabrechnungs-ID aktivieren. Wenn Sie Unterstützung bei der Abrechnung benötigen, wenden Sie sich an den Cloud Billing-Support.
Erstellen oder identifizieren Sie einen Universalschlüssel für Ihr Projekt. Informationen zum Erstellen eines Schlüssels finden Sie unter Universellen Schlüssel erstellen. Alternativ können Sie die ID eines vorhandenen Universalschlüssels kopieren. Führen Sie dazu einen der folgenden Schritte aus:
- So kopieren Sie die ID eines vorhandenen Schlüssels aus der Google Cloud Console:
  1. Rufen Sie in der Google Cloud Console die Seite Google Cloud Fraud Defense auf.
    
    Zu Fraud Defense
  2. Suchen Sie in der Liste Schlüssel den Schlüssel, den Sie kopieren möchten, und klicken Sie auf In Zwischenablage kopieren.
- Wenn Sie die ID eines vorhandenen Schlüssels mit der REST API kopieren möchten, rufen Sie die Methode projects.keys.list auf.
- Wenn Sie die ID eines vorhandenen Schlüssels mit der gcloud CLI kopieren möchten, führen Sie den Befehl gcloud recaptcha keys list aus.
Planen Sie die Einbindung von Fraud Defense, indem Sie die Nutzeraktionen identifizieren, die Sie schützen möchten (z. B. login, signup oder password_reset), und die Seiten auf Ihrer Website, die diese Aktionen auslösen. Wenn Sie die AutoExecute-Konfiguration verwenden, müssen diese Aktionen mit den in der protected_endpoint_group angegebenen Aktionsnamen übereinstimmen.
Fraud Defense in Ihre Webseite einbinden Wir empfehlen, die AutoExecute-Konfiguration von Fraud Defense zu verwenden. Eine allgemeine Anleitung zur Einrichtung finden Sie unter Universelle Schlüssel auf Websites installieren.

Übersicht über die Konfiguration von Fraud Defense-Richtlinien

Mit der Fraud Defense-Richtlinienkonfiguration können Sie das Verhalten Ihres Fraud Defense-Schutzes anpassen. Sie können Challenge-Richtlinien im Abschnitt challenge_rule_groups konfigurieren.

Sie können die Richtlinienkonfiguration mit der Google Cloud Console, der gcloud CLI oder der reCAPTCHA Enterprise REST API aufrufen und aktualisieren.

Console

So rufen Sie Ihre Richtlinienkonfiguration in der Google Cloud Console auf oder aktualisieren sie:

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

Zu Fraud Defense
Achten Sie darauf, dass Ihr Projekt in der Ressourcenauswahl ausgewählt ist.
Klicken Sie in der Tabelle reCAPTCHA-Schlüssel auf den Namen des Schlüssels, für den Sie Challenge-Richtlinien konfigurieren möchten.
Rufen Sie auf der Seite Schlüsseldetails den Tab Richtlinie auf.
Im Bereich Regelgruppen können Sie Ihre Challenge-Regeln und Bedingungsausdrücke ansehen, hinzufügen oder bearbeiten.
Klicken Sie auf Speichern.

gcloud

Führen Sie den Befehl gcloud alpha recaptcha policies update aus, um die Richtlinienkonfiguration für einen Schlüssel zu aktualisieren:

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

Führen Sie den Befehl gcloud alpha recaptcha policies describe aus, um die aktuelle Richtlinienkonfiguration für einen Schlüssel aufzurufen:

gcloud alpha recaptcha policies describe --key=KEY_ID

REST API

Rufen Sie die Methode projects.keys.updatePolicy auf, um die Richtlinienkonfiguration für einen Schlüssel zu aktualisieren:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

Rufen Sie die Methode projects.keys.getPolicy auf, um die aktuelle Richtlinienkonfiguration für einen Schlüssel aufzurufen:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

Die Richtlinienkonfiguration verwendet das YAML-Format für die Google Cloud CLI und das JSON-Format für die REST API. Das vollständige Schema des Abschnitts challenge_rule_groups finden Sie unter Challenge-Richtlinien konfigurieren.

Beispiele für verschiedene Anwendungsfälle finden Sie unter Beispielkonfigurationen für Challenge-Regeln.

Challenge-Richtlinien konfigurieren

Sie konfigurieren Challenge-Richtlinien im Abschnitt challenge_rule_groups der Fraud Defense-Richtlinienkonfiguration. Wenn Sie bereits eine Richtlinie mit client_settings haben, einschließlich der Domaininformationen, können Sie die Richtlinie aktualisieren, um Ihre Challenge-Richtlinienregeln aufzunehmen.

Der Abschnitt challenge_rule_groups hat die folgende Struktur:

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

In jeder Challenge-Regel ist das Feld condition optional. Wenn condition nicht angegeben oder leer ist, gilt die Regel bedingungslos. Außerdem schließen sich die Felder challenge und no_challenge gegenseitig aus und genau eines davon muss in jeder Regel vorhanden sein.

Regelauswertungsreihenfolge

Regelgruppen und die darin enthaltenen Regeln werden nacheinander von oben nach unten ausgewertet. Die erste zutreffende Regel wird angewendet. Wenn weder eine Gruppe noch eine Regel auf die Interaktion zutrifft, erfolgt die Auswertung standardmäßig über die reguläre Bewertung. Es wird keine Herausforderung angezeigt, aber für die Anfrage wird ein Risikowert generiert.

Schwierigkeitsgrade der Aufgaben

Sie können den Schwierigkeitsgrad angeben, wenn Sie eine Challenge auslösen. Eine vollständige Liste der gültigen Schwierigkeitswerte finden Sie in der API-Referenz zu ChallengeSecurityPreference.

Bedingungssyntax

Das Feld condition ist ein optionaler String, der als CEL-Ausdruck (Common Expression Language) formatiert ist. Wenn condition nicht angegeben oder leer ist, gilt die Regel bedingungslos. CEL bietet standardmäßige C-ähnliche Operatoren, einschließlich relationaler (<, <=, >, >=, ==, !=), arithmetischer (+, -, /, *, %), logischer (!, &&, ||) und Container-Operatoren ([], in). CEL unterstützt gängige primitive Datentypen (bool, int, uint, double, string), grundlegende Containertypen (lists, messages) und Konstanten (z. B. true, 1, 0.5, "hello" und [1, 2, 3]).

In der Laufzeit sind die folgenden Fraud Defense-Variablen verfügbar:

Variable	Typ	Beschreibung
`score`	`double`	Der Fraud Defense-Bot-Score.
`user_ip_address`	`string`	Die IP-Adresse (IPv4 oder IPv6) des Nutzers, der die Anfrage stellt.
`user_agent`	`string`	Der User-Agent des Nutzers, der die Anfrage stellt.
`user_asn`	`int`	Die autonome Systemnummer (Autonomous System Number, ASN) des Nutzers, der die Anfrage stellt. Lassen Sie das Präfix `AS` weg (verwenden Sie z. B. `12345` anstelle von `AS12345`).
`region_code`	`string`	Der Unicode-CLDR-Regionscode (basierend auf ISO 3166-1 alpha-2), der dem Standort der Anfrage zugeordnet ist (z. B. `"US"`, `"CA"` oder `"FR"`).
`verified_bots`	`list(Bot)`	Eine Liste verifizierter automatisierter Crawler oder KI-Agenten (z. B. Suchmaschinenindexierer, KI-Suchassistenten und Partnerinhalts-Scraper), die von Fraud Defense identifiziert wurden.

Die folgenden zusätzlichen nicht primitiven Typen sind definiert. Eine vollständige Liste der Werte finden Sie unter Bot.

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

Weitere Informationen zu möglichen name-Werten finden Sie in der API-Referenz zu Bot. Weitere Informationen zu gültigen bot_type-Enum-Werten finden Sie in der API-Referenz zu BotType.

In Fraud Defense-Challenge-Richtlinien können Sie jede dieser Variablen verwenden, um einen booleschen Ausdruck zu erzeugen. Beispielsweise sind score > 0.5, user_ip_address == "192.0.2.1", region_code == "US" und user_asn == 12345 gültige Bedingungsausdrücke, die als boolescher Wert ausgewertet werden. Da user_asn ein Ganzzahltyp ist, müssen Sie das Präfix AS beim Prüfen von ASNs weglassen.

Die folgenden Funktionen sind für die Verwendung in Bedingungen für Fraud Defense-Challenge-Richtlinien verfügbar:

Name	Unterschrift	Beschreibung
`contains`	`string.contains(string) -> bool`	Prüft, ob der String-Operand den Teilstring enthält.
`startsWith`	`string.startsWith(string) -> bool`	Prüft, ob der String-Operand mit dem angegebenen Präfix beginnt.
`endsWith`	`string.endsWith(string) -> bool`	Prüft, ob der Stringoperand mit dem angegebenen Suffix endet.
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	Gibt die Größe eines Strings (Anzahl der Codepunkte) oder einer Liste (Anzahl der Elemente) zurück.

Comprehension-Funktionen sind eine Art von Makro, die in CEL integriert ist. Die folgenden Comprehensions sind verfügbar:

Name	Unterschrift	Beschreibung	Beispiel
`has`	`has(message.field) -> bool`	Prüft, ob ein Feld verfügbar ist.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Prüft, ob alle Elemente `x` in einer Liste `e` mit dem Prädikat `p` übereinstimmen.	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	Prüft, ob ein Element `x` in einer Liste `e` mit dem Prädikat `p` übereinstimmt.	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	Prüft, ob genau ein Element `x` in einer Liste `e` mit dem Prädikat `p` übereinstimmt.	`[1, 2, 2].exists_one(i, i < 2)`

Beispielkonfigurationen für Challenge-Regeln

Dieser Abschnitt enthält Beispiele für gültige Konfigurationen von Challenge-Regeln.

Alle Anfragen mit einer niedrigen Bewertung prüfen

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Wählen Sie eine Challenge mit hohem Reibungswert für alle Anfragen mit einer niedrigen Punktzahl aus.

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

Spezifische Aktionen mit einer niedrigen Punktzahl anfechten

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Unterschiedliche Regelschwellenwerte für verschiedene Aktionen konfigurieren

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

IP-Adressen auf der Zulassungsliste keine Challenge anzeigen

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

Hinweis: Diese Regel unterscheidet sich von der Funktion IP-Zulassungslisten für Fraud Defense.

Subnetz von IP-Adressen keine Aufgabe anzeigen

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

Anfragen von bestimmten ASNs keine Challenge anzeigen

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

Google-Agenten keine Aufgabe anzeigen

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

Aufgabe basierend auf komplexen Bedingungen anzeigen

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

Nächste Schritte

Informationen zum Bewerten des reCAPTCHA-Antworttokens finden Sie unter Bewertungen für Websites erstellen.