Installer des clés universelles sur des pages Web

Ce document explique comment installer et intégrer une clé universelle à vos pages Web.

Avant de commencer

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

  2. Créez une clé universelle et configurez des domaines.

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.

Selon votre approche d'intégration, choisissez l'option appropriée :

Configuration d'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.

  • AutoExecute n'intercepte que les requêtes réseau asynchrones initiées avec l'API Fetch ou XMLHttpRequest, y compris les requêtes provenant de frameworks comme AJAX qui utilisent ces API.
  • AutoExecute n'est pas compatible avec les ressources qui se chargent automatiquement au moment du chargement de la page. Appliquez plutôt AutoExecute aux requêtes réseau déclenchées par des actions de l'utilisateur sur la page, comme un bouton de connexion.
  • Pour éviter que les tests Fraud Defense ne provoquent des délais avant expiration du réseau, appliquez des délais avant expiration directement aux requêtes. Utilisez AbortSignal.timeout(n) pour l'API Fetch et la propriété XMLHttpRequest.timeout pour XMLHttpRequest.

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>

Fraud Defense utilise par défaut 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 en savoir plus sur les langues acceptées, consultez les codes de langue pour Fraud Defense.

Configurer des points de terminaison protégés

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. Cette section définit un mappage des chemins d'URL (path) vers les noms d'action (action).

Si le script Fraud Defense détecte une requête réseau asynchrone vers un chemin mappé, 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.

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 :

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - 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.protectedEndpointGroup

Corps JSON de la requête :

{
"clientSettings": {
  "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.

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 (//).
    • Inclure au moins un segment sans caractère générique (par exemple, ne peut pas être /, /*, /** 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 ; /api/**/login n'est pas valide).
  • 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 interceptera é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 si des conflits de chemins d'accès se produisent.
  • API interdomaines : si votre API de backend est hébergée sur un domaine différent de celui de votre site Web (par exemple, examplecdn.net au lieu de 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é.

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>

    Fraud Defense utilise par défaut 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 en savoir plus sur les langues acceptées, consultez les 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>

    Fraud Defense utilise par défaut 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 en savoir plus sur les langues acceptées, consultez les 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().

    1. 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.

    1. 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