Configurer les règles de validation

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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

Les règles de test vous permettent de déclencher sélectivement des tests CAPTCHA en fonction de règles personnalisées. Ces règles déterminent quand afficher un challenge Fraud Defense en fonction des scores de risque, des adresses IP, des user-agents, des ASN ou des identités de robots (agents d'IA) validées.

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

• Configuration AutoExecute : simplifie l'intégration de JavaScript pour les applications clientes.
• Défis : déclenchent la vérification de l'utilisateur lorsque les règles de vos défis l'exigent. Fraud Defense est compatible avec les types de défis suivants :
  • Défis visuels : demandez aux utilisateurs de sélectionner des images en fonction d'une requête. Par défaut, un défi visuel est sélectionné lorsqu'une règle est configurée avec l'option de défi sélectionnée.
  • Défis audio : demandez aux utilisateurs d'identifier des signaux audio parlés comme alternative d'accessibilité.
  • Défis de code QR : demandez aux utilisateurs de scanner un code QR avec leur appareil mobile pour relever un défi. Votre clé universelle doit figurer sur une liste d'autorisation pour que vous puissiez utiliser cette fonctionnalité. Pour ajouter votre clé universelle à la liste d'autorisation, contactez l'équipe Fraud Defense à l'adresse [e-mail] et fournissez votre clé universelle.

Avant de commencer

1. Préparez votre environnement pour Google Cloud Fraud Defense.
2. 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 Google Cloud existant. Si vous avez besoin d'aide pour la facturation, contactez l'assistance Cloud Billing.

3. 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 opérations 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 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 méthode projects.keys.list.

   • Pour copier l'ID d'une clé existante à l'aide de gcloud CLI, exécutez la commande gcloud recaptcha keys list.

4. Planifiez votre intégration 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 le protected_endpoint_group.

5. 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 de protection contre la fraude

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 validation à l'aide de la section challenge_rule_groups.

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

Console

Pour afficher ou modifier la configuration de votre règle dans la console Google Cloud , procédez comme suit :

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

   Accéder à Fraud Defense

2. Assurez-vous que votre projet est sélectionné dans le sélecteur de ressources.

3. Dans le tableau Clés reCAPTCHA, cliquez sur le nom de la clé pour laquelle vous souhaitez configurer des règles de validation.

4. Sur la page Informations clés, accédez à l'onglet Règle.

5. Dans la section Groupes de règles, vous pouvez afficher, ajouter ou modifier vos règles de défi et vos expressions de condition.

6. Cliquez sur Enregistrer.

gcloud

Pour mettre à jour la configuration de la règle pour 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 d'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 règle 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 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 validation.

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

Configurer les règles de validation

Vous configurez les règles de validation dans la section challenge_rule_groups de la configuration de la stratégie de protection contre la fraude. Si vous disposez déjà d'une règle avec client_settings, y compris les informations sur les domaines, vous pouvez la modifier pour inclure vos règles concernant les défis.

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 défi, 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 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. Aucun défi n'est affiché, mais un score de risque est généré pour la requête.

Niveaux de difficulté des questions d'authentification

Vous pouvez spécifier le niveau de difficulté lorsque vous déclenchez un défi. 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]).

Les variables Fraud Defense suivantes sont accessibles dans le runtime :

Variable	Type	Description
score	double	Score de bot Fraud Defense.
user_ip_address	string	Adresse IP (IPv4 ou IPv6) de l'utilisateur qui envoie 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 demande. Omettez le préfixe AS (par exemple, utilisez 12345 au lieu de AS12345).
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 validation de la défense contre la fraude, vous pouvez utiliser l'une de ces variables pour produire une expression booléenne. Par exemple, score > 0.5, user_ip_address == "192.0.2.1" et user_asn == 12345 sont des expressions de condition valides qui renvoient une valeur booléenne. Notez que, comme 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 validation de la défense contre la fraude :

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 validation

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

Contester toutes les demandes ayant un score faible

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

Sélectionnez un défi à friction élevée pour toutes les demandes avec 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 défi 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é Listes d'adresses IP autorisées pour Fraud Defense.

Ne pas afficher de challenge 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 challenge pour les demandes provenant de certains ASN

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 défi à un agent Google

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

Afficher un défi 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.