Configurer le moteur de règles avec une clé universelle

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 le moteur de règles sur votre site Web à l'aide d'une clé universelle. La clé universelle est une nouvelle clé Google Cloud Fraud Defense qui permet de créer des règles dans le moteur de règles.

Avec Policy Engine, Fraud Defense peut déclencher de manière déterministe des tests CAPTCHA en fonction des règles personnalisées que vous configurez. Ces règles peuvent déterminer quand afficher un défi 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.

La configuration du moteur de règles de protection contre la fraude offre deux fonctionnalités principales :

• Intégration AutoExecute (protected_endpoint_group) : simplifie l'intégration JavaScript du frontend en inspectant automatiquement les requêtes réseau asynchrones sortantes et en leur associant des jetons reCAPTCHA. Ainsi, seule une balise de script est nécessaire sur votre frontend.
• Règles de validation (challenge_rule_groups) : déterminent si une validation doit s'afficher pour différentes actions utilisateur et configurent les niveaux de difficulté de validation associés (USABILITY, BALANCE, SECURITY) à l'aide de règles personnalisées basées sur CEL.

Avant de commencer

1. Préparez votre environnement pour reCAPTCHA.

2. Vérifiez que la facturation est activée pour votre projet Google Cloud .

   Pour utiliser Policy Engine, vous devez associer et activer la facturation sur le projet. 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.

Créer une clé universelle

Selon l'interface de votre choix, sélectionnez l'option appropriée pour créer une clé universelle :

Console

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

   Accéder à reCAPTCHA

2. Vérifiez que le nom de votre projet s'affiche dans le sélecteur de projet en haut de la page.

   Si le nom de votre nouveau projet n'apparaît pas, cliquez sur le sélecteur de projet, puis sélectionnez votre projet.

3. Sélectionnez l'onglet Keys (clés).
4. Cliquez sur Créer une clé.
5. Dans le champ Nom à afficher, saisissez un nom à afficher pour la clé.
6. Dans le champ Type d'application, sélectionnez Universel.
7. Cliquez sur Créer une clé.

La nouvelle clé est répertoriée sur la page Clés reCAPTCHA.

gcloud

Pour créer une clé universelle à l'aide de Google Cloud CLI, utilisez la commande gcloud recaptcha keys create avec le flag --universal :

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

La réponse contient la clé reCAPTCHA universelle nouvellement créée.

API REST

Pour créer une clé universelle à l'aide de l'API REST, utilisez la méthode projects.keys.create et spécifiez universalSettings :

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet Google Cloud
• DISPLAY_NAME : nom à afficher de votre clé, généralement le nom de votre site Web

La réponse contient la clé reCAPTCHA universelle nouvellement créée.

Configurer des domaines pour le moteur de règles

Remarque : Pour les sites Web, la clé reCAPTCHA est unique aux domaines et aux sous-domaines que vous spécifiez. Vous pouvez spécifier plusieurs domaines si vous diffusez votre site Web à partir de plusieurs domaines. Si vous spécifiez un domaine (par exemple, examplepetstore.com), vous n'avez pas besoin de spécifier ses sous-domaines (par exemple, subdomain.examplepetstore.com).

Selon l'interface de votre choix, sélectionnez l'option appropriée pour configurer les domaines autorisés pour votre clé universelle :

Console

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

   Accéder à Fraud Defense

2. Vérifiez que le nom de votre projet s'affiche dans le sélecteur de ressources en haut de la page.

   Si le nom de votre projet n'apparaît pas, cliquez sur le sélecteur de projet, puis sélectionnez votre projet.

3. Cliquez sur l'onglet Clés reCAPTCHA.

4. Identifiez la clé universelle que vous souhaitez configurer, puis cliquez dessus.

5. Sur la page Informations clés, cliquez sur Modifier la clé.

6. Identifiez la section Paramètres d'utilisation de la clé.

   Pour protéger la clé reCAPTCHA pour votre domaine et vos sous-domaines, assurez-vous que l'option Désactiver la validation du domaine est désactivée.

   La désactivation de la validation de domaine est un risque pour la sécurité, car il n'existe aucune restriction sur le site. Par conséquent, votre clé reCAPTCHA est accessible et utilisée par n'importe quel utilisateur.

   Saisissez le nom de domaine de votre site Web :

   1. Dans la section Liste de domaines, cliquez sur Ajouter un domaine.
   2. Dans le champ Domaine, saisissez le nom de votre domaine.
   3. Facultatif : Pour ajouter un domaine supplémentaire, cliquez sur Ajouter un domaine et saisissez le nom d'un autre domaine dans le champ Domaine. Vous pouvez ajouter jusqu'à 250 domaines.

7. Cliquez sur Enregistrer les modifications.

Remarque : Pour appliquer une règle à plus de 250 domaines, cliquez sur le bouton Désactiver la validation du domaine. Lorsque la validation du domaine est désactivée, Fraud Defense ignore la liste des domaines. Vous devez alors valider vous-même le domaine en examinant le champ tokenProperties.hostname dans les évaluations que vous créez.

gcloud

Pour mettre à jour les domaines autorisés pour votre clé universelle à l'aide de Google Cloud CLI, utilisez la commande gcloud alpha recaptcha policies update et spécifiez les domaines dans un fichier de configuration de règles (par exemple, POLICY.yaml) :

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

Remarque : La commande gcloud alpha recaptcha policies update met à jour l'intégralité du règlement. Tout protected_endpoint_group ou challenge_rule_groups existant doit être inclus dans le fichier POLICY.yaml pour éviter de le supprimer.

Le fichier POLICY.yaml doit spécifier les domaines autorisés sous clientSettings :

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

Vous pouvez également autoriser tous les domaines et désactiver la validation du domaine en définissant allowAllDomains sur true dans votre fichier POLICY.yaml :

clientSettings:
  allowAllDomains: true

Remplacez les éléments suivants :

• KEY_ID : ID ou nom complet de la ressource de votre clé universelle
• DOMAIN_NAME_1, DOMAIN_NAME_2 : noms de domaine des sites Web autorisés à utiliser la clé

Remarque : Lorsque allowAllDomains est défini sur true, Fraud Defense ignore la liste de domaines. Vous devez alors valider vous-même le domaine en examinant le champ tokenProperties.hostname dans les évaluations que vous créez.

API REST

Pour mettre à jour les domaines autorisés pour votre clé universelle à l'aide de l'API REST, utilisez la méthode projects.keys.updatePolicy.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• PROJECT_ID : ID de votre projet Google Cloud
• KEY_ID : ID de votre clé universelle
• DOMAIN_NAME_1, DOMAIN_NAME_2 : noms de domaine des sites Web autorisés à utiliser la clé

Méthode HTTP et URL :

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

Corps JSON de la requête :

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

Si la requête aboutit, elle renvoie la configuration de la règle mise à jour.

Remarque : Pour appliquer une règle à plus de 250 domaines, définissez allowAllDomains sur true dans le corps de la requête. Lorsque allowAllDomains est défini sur true, Fraud Defense ignore la liste de domaines et vous devez valider vous-même le domaine en examinant le champ tokenProperties.hostname dans les évaluations que vous créez.

Étapes suivantes

• Installez des clés universelles sur les pages Web.