Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Configurer les règles de validation

Ce document explique comment configurer des règles de test avec une intégration Google Cloud Fraud Defense existante.

Les règles de test vous permettent de déclencher de manière sélective des tests CAPTCHA en fonction de règles personnalisées. Ces règles déterminent quand afficher un test de Fraud Defense en fonction des scores de risque, des adresses IP, des user-agents, des ASN, des régions géographiques ou des identités de bots vérifiées (agents IA).

Vous pouvez utiliser des règles de test avec les fonctionnalités recommandées suivantes :

Configuration AutoExecute : simplifie l'intégration JavaScript pour les applications clientes.
Challenges : déclenche la validation de l'utilisateur lorsque vos règles de challenge l'exigent. Fraud Defense est compatible avec les types de tests suivants :
- Challenges visuels : demandez aux utilisateurs de sélectionner des images en fonction d'une requête. Par défaut, un test visuel est sélectionné lorsqu'une règle est configurée avec l'option de test sélectionnée.
- Challenges audio : demandez aux utilisateurs d'identifier des indices audio parlés comme alternative d'accessibilité.
- Défis avec QR code : demandez aux utilisateurs de scanner un QR code avec leur appareil mobile pour résoudre un défi. Votre clé universelle doit figurer sur une liste d'autorisation pour utiliser cette fonctionnalité. Pour ajouter votre clé universelle à la liste d'autorisation, contactez l'équipe Fraud Defense à l'adresse fraud-defense@google.com et fournissez votre clé universelle.

Avant de commencer

Préparer votre environnement pour Google Cloud Fraud Defense
Vérifiez que la facturation est activée pour votre projet Google Cloud . Vous pouvez activer la facturation à l'aide d'une carte de crédit ou d'un ID de compte de facturation de projet Google Cloud existant. Si vous avez besoin d'aide concernant la facturation, contactez l'assistance Cloud Billing.
Créez ou identifiez une clé universelle pour votre projet. Pour créer une clé, consultez Créer une clé universelle. Vous pouvez également copier l'ID d'une clé universelle existante en procédant de l'une des manières suivantes :
- Pour copier l'ID d'une clé existante à partir de la console Google Cloud , procédez comme suit :
  1. Dans la console Google Cloud , accédez à la page Google Cloud Fraud Defense.
    
    Accéder à Fraud Defense
  2. Dans la liste Clés, recherchez la clé que vous souhaitez copier, puis cliquez sur Copier dans le presse-papiers.
- Pour copier l'ID d'une clé existante à l'aide de l'API REST, appelez la méthode projects.keys.list.
- Pour copier l'ID d'une clé existante à l'aide de la gcloud CLI, exécutez la commande gcloud recaptcha keys list.
Planifiez votre intégration de Fraud Defense en identifiant les actions utilisateur que vous souhaitez protéger (par exemple, login, signup ou password_reset) et les pages de votre site Web qui déclenchent ces actions. Si vous utilisez la configuration AutoExecute, assurez-vous que ces actions sont cohérentes avec les noms d'action spécifiés dans protected_endpoint_group.
Intégrez Fraud Defense à votre page Web. Nous vous recommandons d'utiliser la configuration AutoExecute de Fraud Defense. Pour obtenir des instructions de configuration générales, consultez Installer des clés universelles sur des sites Web.

Présentation de la configuration des règles Fraud Defense

La configuration de la stratégie Fraud Defense vous permet de personnaliser le comportement de votre protection Fraud Defense. Vous pouvez configurer des règles de test à l'aide de la section challenge_rule_groups.

Vous pouvez afficher et mettre à jour la configuration de la stratégie à l'aide de la console Google Cloud , de la gcloud CLI ou de l'API REST reCAPTCHA Enterprise.

Console

Pour afficher ou mettre à jour la configuration de votre stratégie dans la console Google Cloud , procédez comme suit :

Dans la console Google Cloud , accédez à la page Fraud Defense.

Accéder à Fraud Defense
Assurez-vous que votre projet est sélectionné dans le sélecteur de ressources.
Dans le tableau Clés reCAPTCHA, cliquez sur le nom de la clé pour laquelle vous souhaitez configurer des règles de test.
Sur la page Détails de la clé, accédez à l'onglet Règle.
Dans la section Groupes de règles, vous pouvez afficher, ajouter ou modifier vos règles de test et vos expressions de condition.
Cliquez sur Enregistrer.

gcloud

Pour mettre à jour la configuration de la stratégie d'une clé, exécutez la commande gcloud alpha recaptcha policies update :

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

Pour afficher la configuration actuelle de la stratégie pour une clé, exécutez la commande gcloud alpha recaptcha policies describe :

gcloud alpha recaptcha policies describe --key=KEY_ID

API REST

Pour mettre à jour la configuration de la stratégie d'une clé, appelez la méthode projects.keys.updatePolicy :

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": {}
        }
      ]
    }
  ]
}

Pour afficher la configuration actuelle de la stratégie pour une clé, appelez la méthode projects.keys.getPolicy :

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

La configuration de la stratégie utilise le format YAML pour la Google Cloud CLI et le format JSON pour l'API REST. Pour obtenir le schéma complet de la section challenge_rule_groups, consultez Configurer des règles de test.

Pour obtenir des exemples de différents cas d'utilisation, consultez Exemples de configurations de règles de test.

Configurer des règles de test

Vous configurez les règles de test dans la section challenge_rule_groups de la configuration de la règle Fraud Defense. Si vous disposez déjà d'une règle avec client_settings, y compris les informations sur les domaines, vous pouvez mettre à jour la règle pour inclure vos règles de stratégie de test.

La section challenge_rule_groups présente la structure suivante :

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: {}

Dans chaque règle de test, le champ condition est facultatif. Si condition n'est pas spécifié ou est vide, la règle s'applique sans condition. De plus, les champs challenge et no_challenge s'excluent mutuellement, et un seul d'entre eux doit être présent dans chaque règle.

Ordre d'évaluation des règles

Les groupes de règles et leurs règles internes sont évalués dans l'ordre de haut en bas. La première règle correspondante est appliquée. Lorsqu'aucun groupe ni aucune règle ne correspond à l'interaction, l'évaluation reCAPTCHA standard est effectuée par défaut (aucun test n'est affiché), mais un score de risque est généré pour la requête.

Niveaux de difficulté des tests

Vous pouvez spécifier le niveau de difficulté lorsque vous déclenchez un challenge. Pour obtenir la liste complète des valeurs de difficulté valides, consultez la documentation de référence de l'API ChallengeSecurityPreference.

Syntaxe des conditions

Le champ condition est une chaîne facultative au format d'expression CEL (Common Expression Language). Si condition n'est pas spécifié ou est vide, la règle s'applique sans condition. CEL fournit des opérateurs standards de type C, y compris des opérateurs relationnels (<, <=, >, >=, ==, !=), arithmétiques (+, -, /, *, %), logiques (!, &&, ||) et de conteneur ([], in). CEL est compatible avec les types de données primitifs courants (bool, int, uint, double, string), les types de conteneurs de base (lists, messages) et les constantes (telles que true, 1, 0.5, "hello" et [1, 2, 3]).

Dans l'environnement d'exécution, les variables Fraud Defense suivantes sont accessibles :

Variable	Type	Description
`score`	`double`	Score de bot Fraud Defense.
`user_ip_address`	`string`	Adresse IP (IPv4 ou IPv6) de l'utilisateur à l'origine de la requête.
`user_agent`	`string`	User-agent de l'utilisateur qui effectue la requête.
`user_asn`	`int`	Numéro de système autonome (ASN) de l'utilisateur qui effectue la requête. Omettez le préfixe `AS` (par exemple, utilisez `12345` au lieu de `AS12345`).
`region_code`	`string`	Code de région CLDR Unicode (basé sur la norme ISO 3166-1 alpha-2) associé à l'emplacement de la requête (par exemple, `"US"`, `"CA"` ou `"FR"`).
`verified_bots`	`list(Bot)`	Liste des robots d'exploration ou agents automatisés validés (tels que les outils d'indexation de moteurs de recherche, les assistants de recherche optimisée par l'IA et les scrapers de contenus partenaires) que Fraud Defense a identifiés.

Les types non primitifs supplémentaires suivants sont définis. Pour obtenir la liste complète des valeurs, consultez Bot.

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

Pour en savoir plus sur les valeurs name possibles, consultez la documentation de référence de l'API Bot. Pour en savoir plus sur les valeurs d'énumération bot_type valides, consultez la documentation de référence de l'API BotType.

Dans les règles de test de Fraud Defense, vous pouvez utiliser n'importe laquelle de ces variables pour produire une expression booléenne. Par exemple, score > 0.5, user_ip_address == "192.0.2.1", region_code == "US" et user_asn == 12345 sont des expressions de condition valides qui renvoient une valeur booléenne. Notez que, comme user_asn est un type d'entier, vous devez omettre le préfixe AS lorsque vous vérifiez les ASN.

Les fonctions suivantes sont disponibles pour les conditions de règle de test Fraud Defense :

Nom	Signature	Description
`contains`	`string.contains(string) -> bool`	Vérifie si l'opérande de chaîne contient la sous-chaîne.
`startsWith`	`string.startsWith(string) -> bool`	Vérifie si l'opérande de chaîne commence par le préfixe spécifié.
`endsWith`	`string.endsWith(string) -> bool`	Vérifie si l'opérande de chaîne se termine par le suffixe spécifié.
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	Renvoie la taille d'une chaîne (nombre de points de code) ou d'une liste (nombre d'éléments).

Les fonctions de compréhension sont un style de macro intégré à CEL. Les compréhensions suivantes sont disponibles :

Nom	Signature	Description	Exemple
`has`	`has(message.field) -> bool`	Vérifie si un champ est disponible.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Vérifie si tous les éléments `x` d'une liste `e` correspondent au prédicat `p`.	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	Vérifie si un élément `x` d'une liste `e` correspond au prédicat `p`.	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	Vérifie si un seul élément `x` d'une liste `e` correspond au prédicat `p`.	`[1, 2, 2].exists_one(i, i < 2)`

Exemples de configurations de règles de test

Cette section contient des exemples de configuration de règles de test valides.

Contrôler toutes les requêtes ayant un score faible

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

Sélectionnez un test à friction élevée pour toutes les requêtes ayant un score faible.

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

Contester des actions spécifiques ayant un score faible

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

Configurer différents seuils de règles pour différentes actions

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

Ne pas afficher de question d'authentification pour les adresses IP de la liste d'autorisation

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

Remarque : Cette règle est distincte de la fonctionnalité Listes d'autorisation d'adresses IP pour Fraud Defense.

Ne pas afficher de question d'authentification pour un sous-réseau d'adresses IP

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

Ne pas afficher de test pour les requêtes provenant de numéros ASN spécifiques

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: {}

Ne pas afficher le challenge à un agent Google

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

Afficher un test en fonction de conditions complexes

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

Étapes suivantes

Pour évaluer le jeton de réponse reCAPTCHA, consultez Créer des évaluations pour les sites Web.