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éparez 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, choisissez la configuration AutoExecute de Google Cloud Fraud Defense ou l'installation JavaScript standard :

Configuration AutoExecute

Fraud Defense AutoExecute peut vous aider à simplifier l'intégration JavaScript de votre interface en interceptant les requêtes réseau sur vos pages Web, ce qui vous évite d'avoir à appeler manuellement grecaptcha.enterprise.execute() pour chaque action d'interface.

  • AutoExecute n'intercepte que les requêtes réseau asynchrones initiées avec the l'API Fetch ou XMLHttpRequest, y compris les requêtes provenant de frameworks tels qu'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 n'entraînent des délais d'attente réseau, appliquez directement des délais d'attente aux requêtes. Utilisez AbortSignal.timeout(n) pour l' API Fetch et la propriété XMLHttpRequest.timeout pour XMLHttpRequest.

    • Ajouter la balise de script à vos pages Web

    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' hl=LANG attribut 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 compatibles, 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) aux noms d'action (action).

    Si le script Fraud Defense détecte une requête réseau asynchrone vers un chemin mappé, il intercepte la requête, déclenche une évaluation des risques et affiche éventuellement 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 de la stratégie de votre clé universelle, utilisez la gcloud alpha recaptcha policies describe commande :

    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 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 gcloud alpha recaptcha policies update commande :

    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 projects.keys.updatePolicy méthode.

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

    • PROJECT_ID: ID de votre Google Cloud projet
    • 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 la stratégie mise à jour.

    Le paramètre path est compatible avec les modèles glob selon les règles suivantes :

    • Doit commencer par / et ne peut pas être vide.
    • Ne peut pas être un /* ou /** autonome, car le déclenchement de Fraud Defense pour chaque requête adressée à votre backend peut avoir un impact négatif sur les performances.
    • Les caractères génériques * (correspondant à un seul segment de chemin) et ** (correspondant à plusieurs segments de chemin) doivent occuper l'intégralité d'un segment de chemin (par exemple, /api/*/login ou /api/* sont valides, mais /api/login* ne l'est pas).
    • Le caractère générique ** ne doit occuper que le dernier segment de chemin (par exemple, /api/** est valide, mais /api/**/login ne l'est pas).
    • Requêtes tierces : si des outils tiers s'exécutant sur votre page (tels que des scripts d'analyse ou de partenaires) envoient des requêtes à des chemins 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 protégés sont distincts (par exemple, /auth/v1/login) ou utilisez l'installation standard en cas de collision de chemins.
    • 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 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 de l'en-tête de requête X-Recaptcha-Token et créez une évaluation dans les deux minutes.

    Installation standard

    Nous vous recommandons d'ajouter la validation Fraud Defense sur 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 à cette action.

    En fonction de l'emplacement où vous souhaitez ajouter la validation Fraud Defense, choisissez l'option appropriée :

    Ajouter une validation sur une interaction de l'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' hl=LANG attribut 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 compatibles, 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 la balise de script. Par exemple, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Par défaut, l'emplacement est défini sur bottomright. Les autres valeurs possibles sont inline et bottomleft.

    2. Pour ajouter la validation Fraud Defense sur 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. Indiquez un nom explicite pour une interaction de l'utilisateur dans le paramètre action. Pour en savoir plus, consultez la section 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>

        s

    3. Une fois le jeton généré, envoyez le jeton reCAPTCHA à 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' hl=LANG attribut 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 compatibles, consultez les codes de langue pour Fraud Defense.

    2. Pour ajouter Fraud Defense sur 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' data-badge="LOCATION" attribut sur l' élément qui comporte class="g-recaptcha". Par défaut, l'emplacement est défini sur bottomright. Les autres valeurs possibles sont inline et bottomleft.

      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 généré, envoyez le jeton reCAPTCHA à votre backend et créez une évaluation dans les deux minutes.

    Étape suivante