Installer des clés universelles sur des pages Web

Une clé universelle Fraud Defense permet de protéger vos applications Web et vos points de terminaison d'API contre les attaques de bots automatisées, l'utilisation abusive d'identifiants et la fraude. En utilisant une clé universelle, vous pouvez déployer des protections sur votre site Web avec l'interception automatisée des requêtes réseau (AutoExecute), l'exécution manuelle de JavaScript ou une combinaison des deux méthodes.

Avant de commencer

  1. Préparer votre environnement pour Google Cloud Fraud Defense

  2. Créez une clé universelle.

  3. Configurez des domaines pour votre clé universelle.

  4. Pour afficher la colonne État des points de terminaison protégés dans la consoleGoogle Cloud , assurez-vous de disposer de l'autorisation Cloud Monitoringmonitoring.timeSeries.list. Cette autorisation est incluse dans les rôles Fraud Defense prédéfinis : Administrateur reCAPTCHA Enterprise, Éditeur reCAPTCHA Enterprise et Lecteur reCAPTCHA Enterprise.

Installer des clés universelles sur votre site Web

Pour installer votre clé universelle et protéger vos pages Web, vous pouvez utiliser la configuration AutoExecute, l'installation manuelle de JavaScript ou les deux méthodes ensemble sur différents points de terminaison à l'aide de la même clé universelle :

  • Configuration AutoExecute (recommandée) : intercepte automatiquement les requêtes réseau asynchrones vers les chemins d'URL configurés et associe le jeton reCAPTCHA à l'en-tête de requête.
  • Installation manuelle : utilise des appels grecaptcha.enterprise.execute() manuels ou des attributs de bouton HTML. Vous pouvez utiliser cette méthode seule ou avec AutoExecute pour les requêtes réseau non compatibles avec AutoExecute, les requêtes nécessitant un emplacement de jeton personnalisé dans la charge utile ou lors des migrations incrémentielles vers AutoExecute.

Configurer AutoExecute

AutoExecute peut vous aider à simplifier l'intégration JavaScript de votre interface en interceptant les requêtes réseau sur vos pages Web et en éliminant les appels grecaptcha.enterprise.execute() manuels pour chaque action d'interface.

Fonctionnement d'AutoExecute

Le script Fraud Defense s'intègre automatiquement aux actions réseau définies dans la configuration de la stratégie de votre clé universelle. Lorsque le script détecte une requête réseau asynchrone vers un chemin configuré, il l'intercepte, déclenche une évaluation des risques et peut afficher un test CAPTCHA à l'utilisateur avant que la requête d'origine ne se poursuive. Le jeton de réponse généré est automatiquement associé à l'en-tête X-Recaptcha-Token de la requête.

API réseau compatibles

AutoExecute n'intercepte que les requêtes réseau asynchrones initiées par les API suivantes (y compris les frameworks comme AJAX qui s'appuient sur elles) :

Nom de l'API Configuration du délai avant expiration Exemple de mise en œuvre
API Fetch Définissez des délais avant expiration à l'aide du contrôleur AbortSignal. AbortSignal.timeout(n)
XMLHttpRequest Définissez des délais avant expiration à l'aide de la propriété native .timeout. xhr.timeout = n

Bonnes pratiques d'intégration

  • Actions déclenchées par l'utilisateur uniquement : AutoExecute n'est pas compatible avec les ressources qui se chargent automatiquement lors du chargement de la page. Pour éviter l'échec de l'intégration, n'appliquez AutoExecute qu'aux requêtes déclenchées par des interactions utilisateur explicites (par exemple, un clic sur un bouton de connexion ou d'envoi).
  • Éviter les délais d'inactivité liés à la latence : les flux de vérification de Fraud Defense peuvent parfois entraîner des retards réseau. Pour éviter les délais avant expiration côté client, configurez toujours des délais avant expiration explicites pour les requêtes directement à l'aide des mécanismes listés dans le tableau.
  • Protéger uniquement les chemins d'accès sensibles : spécifiez protectedEndpoints uniquement pour les chemins d'accès sensibles et utilisez un nom explicite pour l'interaction utilisateur dans le paramètre action. Évitez de protéger tous les points de terminaison, car le déclenchement de Fraud Defense sur chaque requête de backend peut avoir un impact négatif sur les performances. Pour en savoir plus, consultez Actions.

Ajouter le tag de script à vos pages Web

Pour charger Fraud Defense sur votre page Web, ajoutez l'API JavaScript avec votre clé universelle dans l'élément <head></head> de votre page Web :

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Par défaut, Fraud Defense utilise la langue du navigateur. Si vous souhaitez spécifier une autre langue, utilisez l'attribut hl=LANG dans votre script. Par exemple, pour utiliser le français, spécifiez ce qui suit :

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Pour connaître les langues acceptées, consultez Codes de langue pour Fraud Defense.

Configurer des points de terminaison protégés

Pour configurer des points de terminaison protégés pour votre clé universelle, sélectionnez un onglet :

Console

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

    Accéder à Fraud Defense

  2. Dans la barre d'outils de la console, vérifiez que votre projet apparaît dans le sélecteur de ressources. Si ce n'est pas le cas, cliquez sur le sélecteur de ressources, puis sélectionnez votre projet.

  3. Sélectionnez l'onglet Keys (clés).

    L'onglet Clés comporte deux vues : Fiches et Tableau. Si votre projet comporte de nombreuses clés, seule la vue Tableau est disponible.

  4. Dans la section Clés reCAPTCHA, recherchez la clé universelle que vous souhaitez configurer :

    • Dans la vue Fiches, cliquez sur Détails de la clé sur la fiche de la clé.
    • Dans la vue Table, cliquez sur le nom de la clé.

  5. Sur la page Détails de la clé, cliquez sur l'onglet Intégration.

  6. À l'étape Ajouter reCAPTCHA à votre site Web, sélectionnez l'onglet AutoExecute (recommandé).

    Facultatif : Pour protéger manuellement des points de terminaison spécifiques, cliquez sur l'onglet Manuel pour afficher l'extrait de code grecaptcha.enterprise.execute().

  7. Dans la section Points de terminaison protégés, cliquez sur Ajouter un point de terminaison pour configurer chaque point de terminaison que vous souhaitez protéger :

    1. Dans le champ Action, saisissez un nom pour l'interaction utilisateur. Par exemple, login, register ou add_to_cart. Pour en savoir plus, consultez Actions.
    2. Dans le champ Chemin d'accès, saisissez le chemin d'URL unique ou le format glob à intercepter. Par exemple, /login_api, /register_api ou /cart_api/add/*.
    3. (Facultatif) Pour ajouter un autre point de terminaison, cliquez sur Ajouter un point de terminaison.

  8. Cliquez sur Enregistrer pour enregistrer vos points de terminaison protégés.

Une fois votre configuration enregistrée, la colonne État du tableau Points de terminaison protégés indique si Fraud Defense a reçu du trafic pour chaque action au cours des dernières 24 heures. La mise à jour de l'état du trafic peut prendre 10 minutes après la première réception du trafic par un point de terminaison.

gcloud

Pour inspecter la configuration actuelle des règles de votre clé universelle, utilisez la commande gcloud alpha recaptcha policies describe :

gcloud alpha recaptcha policies describe --key=KEY_ID

Pour mettre à jour la configuration de la stratégie avec vos points de terminaison protégés, créez un fichier YAML (par exemple, POLICY.yaml) définissant vos chemins d'accès et actions protégés :

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Mettez à jour la configuration de votre clé avec le fichier YAML à l'aide de la commande gcloud alpha recaptcha policies update :

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

API REST

Pour mettre à jour la configuration de la stratégie afin de définir des points de terminaison protégés à 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

Méthode HTTP et URL : 

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

Corps JSON de la requête :

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

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

Si la requête aboutit, elle renvoie la configuration de stratégie mise à jour.

Syntaxe et limites des points de terminaison protégés

Vous pouvez configurer jusqu'à 25 points de terminaison protégés par clé universelle. Chaque point de terminaison doit répondre aux exigences suivantes :

  • action : le nom de l'action doit comporter entre 1 et 100 caractères, et ne contenir que des lettres, des chiffres, des barres obliques (/) et des traits de soulignement (_).
  • path (sensible à la casse) : le chemin d'accès doit répondre aux critères suivants :
    • Être unique, commencer par / et contenir entre 1 et 200 caractères sans barres obliques consécutives (//).
    • Incluez au moins un segment qui n'est pas un caractère générique. Par exemple, il ne peut pas s'agir de /, /*, /** ou /*/.
    • Les caractères génériques doivent occuper des segments complets : * correspond à un seul segment. Par exemple, /api/*/login ou /api/* sont valides, /api/login* n'est pas valide et ** correspond à plusieurs segments en tant que segment final uniquement. Par exemple, /api/** est valide, mais pas /api/**/login.

Comportement de mise en correspondance des chemins d'accès

AutoExecute évalue les points de terminaison protégés de manière séquentielle, de haut en bas, par rapport au chemin d'URL uniquement. Il ignore le domaine, le schéma et les paramètres de requête de destination. Ce comportement a les implications pratiques suivantes :

  • Ordre de correspondance des chemins d'accès : AutoExecute applique le premier point de terminaison correspondant. Si aucun point de terminaison ne correspond, AutoExecute n'intercepte pas la requête. Placez les chemins spécifiques avant les modèles de caractères génériques pour éviter de masquer des routes plus spécifiques. Par exemple, listez /mysite/login avant /*/login.
  • Requêtes tierces : si des outils tiers exécutés sur votre page (comme des scripts d'analyse ou de partenaires) envoient des requêtes à des chemins d'accès correspondant à vos points de terminaison protégés (par exemple, https://analytics.example.net/login correspondant à /login), AutoExecute les intercepte également. Cela peut entraîner une latence réseau supplémentaire, des métriques faussées ou des tests CAPTCHA inattendus. Pour éviter les conflits, assurez-vous que vos chemins d'accès protégés sont distincts (par exemple, /auth/v1/login) ou utilisez l'installation manuelle en cas de collision de chemins d'accès.
  • API interdomaines : si votre API de backend est hébergée sur un domaine différent de celui de votre site Web (par exemple, cdn.example.com par rapport à www.example.com), AutoExecute fonctionne automatiquement sans configuration de domaine supplémentaire.

Si la mise en correspondance avec des domaines de destination spécifiques est importante pour votre intégration, envoyez une demande de fonctionnalité.

Valider les jetons dans votre backend

Dans votre backend, récupérez le jeton de réponse à partir de l'en-tête de requête X-Recaptcha-Token et créez une évaluation dans un délai de deux minutes.

Installation manuelle

Nous vous recommandons d'ajouter la validation Fraud Defense à une interaction utilisateur qui doit être validée. Par exemple, si vous souhaitez valider l'action d'envoi d'un formulaire, vous devez ajouter la validation Fraud Defense à l'action d'envoi.

Selon l'endroit où vous souhaitez ajouter la validation Fraud Defense, choisissez l'option appropriée :

Ajouter une validation lors d'une interaction utilisateur

  1. Pour charger reCAPTCHA sur votre page Web, ajoutez l'API JavaScript avec votre clé universelle dans l'élément <head></head> de votre page Web :

    <head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

    Par défaut, Fraud Defense utilise la langue du navigateur. Si vous souhaitez spécifier une autre langue, utilisez l'attribut hl=LANG dans votre script. Par exemple, pour utiliser le français, spécifiez ce qui suit :

    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

    Pour connaître les langues acceptées, consultez Codes de langue pour Fraud Defense.

    Si vous souhaitez spécifier un emplacement pour le badge, utilisez badge=LOCATION comme paramètre de requête dans le tag de script. Exemple : https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Par défaut, l'emplacement est défini sur bottomright. inline et bottomleft sont d'autres valeurs possibles.

  2. Pour ajouter la validation Fraud Defense à une interaction utilisateur, procédez comme suit :

    1. Pour vous assurer que grecaptcha.enterprise.execute() s'exécute après le chargement de la bibliothèque Fraud Defense, utilisez grecaptcha.enterprise.ready().

    2. Appelez grecaptcha.enterprise.execute() pour chaque interaction que vous souhaitez protéger avec votre clé universelle. Spécifiez un nom explicite pour une interaction utilisateur dans le paramètre action. Pour en savoir plus, consultez Actions.

      L'exemple suivant montre comment appeler grecaptcha.enterprise.execute() sur une action de connexion :

      <script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>

  3. Une fois le jeton reCAPTCHA généré, envoyez-le à votre backend et créez une évaluation dans les deux minutes.

Ajouter Fraud Defense sur un bouton HTML

  1. Pour charger reCAPTCHA sur votre page Web, ajoutez l'API JavaScript avec votre clé universelle dans l'élément <head></head> de votre page Web :

    <head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

    Par défaut, Fraud Defense utilise la langue du navigateur. Si vous souhaitez spécifier une autre langue, utilisez l'attribut hl=LANG dans votre script. Par exemple, pour utiliser le français, spécifiez ce qui suit :

    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

    Pour connaître les langues acceptées, consultez Codes de langue pour Fraud Defense.

  2. Pour ajouter Fraud Defense à un bouton HTML, procédez comme suit :

    1. Définissez une fonction de rappel pour gérer le jeton.

      <script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>

      Pour en savoir plus, consultez la méthode requestSubmit().

    2. Ajoutez des attributs à votre bouton HTML.

      <button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>

      Si vous souhaitez spécifier un emplacement pour le badge, utilisez l'attribut data-badge="LOCATION" sur l'élément qui comporte class="g-recaptcha". Par défaut, l'emplacement est défini sur bottomright. inline et bottomleft sont d'autres valeurs possibles.

    3. Lorsque ce bouton est utilisé pour envoyer un formulaire sur votre site, le jeton de réponse est inclus dans le paramètre POST g-recaptcha-response.

  3. Une fois le jeton reCAPTCHA généré, envoyez-le à votre backend et créez une évaluation dans les deux minutes.

Étapes suivantes