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 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 robots validés (agents d'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.
Tests : déclenche la validation de l'utilisateur lorsque les règles de test l'exigent. Fraud Defense est compatible avec les types de tests suivants :
- Tests visuels : demandent aux utilisateurs de sélectionner des images en fonction d'une invite. Par défaut, un test visuel est sélectionné lorsqu'une règle est configurée avec l'option de test sélectionnée.
- Tests audio : demandent aux utilisateurs d'identifier des signaux audio parlés comme alternative d' accessibilité.
- Tests de QR code : demandent aux utilisateurs de scanner un QR code avec leur appareil mobile pour résoudre un test. 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éparez votre environnement pour Google Cloud Fraud Defense.
Vérifiez que la facturation est activée pour votre Google Cloud projet. Vous pouvez activer la facturation à l'aide d'une carte de crédit ou d'un ID de compte de facturation de projet existant Google Cloud . Si vous avez besoin d'aide pour 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 effectuant l'une des étapes suivantes :
- Pour copier l'ID d'une clé existante à partir de la Google Cloud console, procédez comme suit :
  1. Dans la Google Cloud console, accédez à la page Google Cloud Fraud Defense.
    
    Accéder à Fraud Defense
  2. Dans la liste Clés reCAPTCHA , 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 projects.keys.list méthode.
- Pour copier l'ID d'une clé existante à l'aide de gcloud CLI, exécutez la gcloud recaptcha keys list commande.
Planifiez votre intégration Fraud Defense en identifiant les actions utilisateur que vous souhaitez protéger (telles que 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 le 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 des règles 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 des règles à l'aide de la Google Cloud console, de gcloud CLI ou de l'API REST reCAPTCHA Enterprise.

Console

Pour afficher ou mettre à jour la configuration de vos règles dans la Google Cloud console, procédez comme suit :

Dans la Google Cloud console, 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ègles.
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 des règles d'une clé, exécutez la gcloud alpha recaptcha policies update commande :

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

Pour afficher la configuration actuelle des règles d'une clé, exécutez la gcloud alpha recaptcha policies describe commande :

gcloud alpha recaptcha policies describe --key=KEY_ID

API REST

Pour mettre à jour la configuration des règles d'une clé, appelez la projects.keys.updatePolicy méthode :

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 des règles d'une clé, appelez la projects.keys.getPolicy méthode :

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

La configuration des règles utilise le format YAML pour 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 des règles de test dans la section challenge_rule_groups de la configuration des règles Fraud Defense. Si vous disposez déjà d'une règle avec client_settings, y compris les informations sur les domaines, vous pouvez la mettre à jour pour inclure vos règles 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. En outre, les champs challenge et no_challenge s'excluent mutuellement, et l'un d'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 standard est effectuée par défaut sans qu'aucun test ne soit 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 test. 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 mise en forme en tant qu'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]).

Au moment de l'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 qui effectue 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 Unicode CLDR (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 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 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. Étant donné que user_asn est un type entier, vous devez omettre le préfixe AS lorsque vous vérifiez les ASN.

Les fonctions suivantes peuvent être utilisées dans les conditions des règles 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 exactement un é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 configurations de règles de test valides.

Tester toutes les requêtes dont le score est faible

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

Sélectionner un test à friction élevée pour toutes les requêtes dont le score est faible

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

Tester des actions spécifiques dont le score est 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 test pour les adresses IP figurant sur 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é de liste d'autorisation d'adresses IP de Fraud Defense.

Ne pas afficher de test 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 d'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 de test pour 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: {}

Étape suivante

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