Implémenter les fonctionnalités d'intégration de reCAPTCHA Enterprise pour WAF et Google Cloud Armor

Ce document explique comment implémenter la page de test reCAPTCHA, les jetons d'action reCAPTCHA et les jetons de session reCAPTCHA pour Google Cloud Armor.

Avant de commencer

Pour utiliser des jetons d'action ou des jetons de session reCAPTCHA, activez l'API reCAPTCHA Enterprise en procédant comme suit :

  1. Dans Cloud Console, accédez à la page API reCAPTCHA Enterprise.

    Accéder à l'API reCAPTCHA Enterprise

  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. Cliquez sur Activer.

Implémenter la page de test reCAPTCHA

Vous n'avez aucune étape à effectuer pour implémenter la page de test reCAPTCHA, car reCAPTCHA Enterprise gère automatiquement la mise en œuvre.

À l'étape suivante, configurez les stratégies de sécurité Google Cloud Armor.

Implémenter des jetons d'action reCAPTCHA

Vous devez exécuter reCAPTCHA Enterprise sur vos pages Web pour générer des jetons d'action. Une fois que reCAPTCHA Enterprise a généré un jeton d'action, vous devez l'associer à un en-tête de requête prédéfini partout où vous devez protéger les actions utilisateur, telle que le règlement. Par défaut, les jetons d'action sont valides pendant 30 minutes. Ce délai peut être réduit. Par conséquent, vous devez associer le jeton d'action à un en-tête de requête prédéfini avant son expiration, afin que Google Cloud Armor puisse évaluer les attributs du jeton.

Pour implémenter un jeton d'action reCAPTCHA, procédez comme suit :

  1. Créez une clé de site reCAPTCHA basée sur des scores ou une case à cocher.
  2. Pour activer la fonctionnalité de jeton d'action pour la clé de site, envoyez la clé de site à recaptcha-waf-eng@google.com.
  3. Une fois la fonctionnalité de jeton d'action activée pour la clé de site, vous recevez un e-mail de confirmation.
  4. Sur vos pages Web, installez la clé de site activée. Pour obtenir des instructions, reportez-vous au document correspondant à la clé de votre site :

  5. Après avoir reçu le jeton de reCAPTCHA Enterprise, associez-le à un en-tête de requête prédéfini au format suivant :

       X-Recaptcha-Token:value-of-your-action-token
    

    Vous pouvez utiliser des langages tels que XHR, Ajax et l'API Fetch pour associer le jeton à un en-tête de requête prédéfini.

L'exemple de script suivant montre comment protéger l'action d'exécution et associer le jeton à un en-tête de requête prédéfini à l'aide de JavaScript + XHR :

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

    <script>

     function onSuccess(action_token) {
       const xhr = new XMLHttpRequest();
       xhr.open('GET','YOUR_URL', false);
       // Attach the action-token to the predefined request header
       xhr.setRequestHeader("X-Recaptcha-Token", action_token);
       xhr.send(null);
     }

     function onError(reason) {
       alert('Response promise rejected: ' + reason);
     }

     grecaptcha.enterprise.ready(function () {
       document.getElementById("execute-button").onclick = () => {
         grecaptcha.enterprise.execute('SITE_KEY_ACTION_TOKEN_ENABLED', {
         }).then(onSuccess, onError);
       };
     });
    </script>

À l'étape suivante, configurez les stratégies de sécurité Google Cloud Armor.

Implémenter des jetons de session reCAPTCHA

Le code JavaScript reCAPTCHA définit un jeton de session reCAPTCHA en tant que cookie sur le navigateur de l'utilisateur final après l'évaluation. Le navigateur de l'utilisateur final associe le cookie et l'actualise tant que le code JavaScript reCAPTCHA reste actif.

Pour fournir un jeton de session en tant que cookie, installez une clé de site reCAPTCHA basée sur des scores sur au moins l'une de vos pages Web qui répond aux exigences suivantes :

  • La page Web doit être la page que l'utilisateur final parcourt avant la page à protéger. Par exemple, si vous souhaitez protéger la page de paiement, installez la clé de site basée sur des scores reCAPTCHA sur la page d'accueil ou sur la page du produit.
  • La page Web est protégée par une stratégie de sécurité Google Cloud Armor.

Vous pouvez utiliser ce cookie pour protéger les requêtes ultérieures de l'utilisateur et les chargements de page sur un domaine spécifique. Les jetons de session sont valides par défaut pendant 30 minutes. Toutefois, si l'utilisateur reste sur la page où vous avez implémenté le jeton de session, reCAPTCHA Enterprise actualise régulièrement le jeton de session pour empêcher son expiration.

Installez des jetons de session sur chaque page devant être protégée par reCAPTCHA Enterprise. Nous vous recommandons d'installer reCAPTCHA Enterprise sur chaque page et d'utiliser des règles Google Cloud Armor pour appliquer l'accès à toutes les pages, à l'exception de la première page que les utilisateurs finaux parcourent.

Voici un exemple de jeton de session reCAPTCHA :

   recaptcha-ca-t=value-of-your-session-token;domain=domain;expires=expiration_time

Pour implémenter un jeton de session reCAPTCHA, procédez comme suit :

  1. Créez une clé de site reCAPTCHA basée sur des scores.
  2. Pour activer la fonctionnalité de jeton de session pour la clé de site, envoyez la clé de site à recaptcha-waf-eng@google.com.
  3. Une fois la fonctionnalité de jeton de session activée pour la clé de site, vous recevez un e-mail de confirmation.
  4. Ajoutez la clé de site activée avec la fonctionnalité de jeton de session et waf=session au code JavaScript reCAPTCHA.

L'exemple de script suivant montre comment implémenter un jeton de session sur une page Web :

    <!DOCTYPE html>
    <html lang="en">
    <head>
     <meta charset="UTF-8">
     <title>reCAPTCHA WAF Session Token</title>
     <script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY_SESSION_TOKEN_ENABLED&waf=session" async defer></script>
    </head>
  </html>

À l'étape suivante, configurez les stratégies de sécurité Google Cloud Armor.

Exemples d'utilisation de plusieurs fonctionnalités dans une même application

Vous pouvez utiliser une ou plusieurs fonctionnalités reCAPTCHA Enterprise pour les fonctionnalités WAF dans une seule application.

Exemple 1 : Utiliser la page de test reCAPTCHA et les jetons de session reCAPTCHA

Vous pouvez ajouter un jeton de session reCAPTCHA sur les pages auxquelles un utilisateur peut accéder afin que le cookie soit actualisé régulièrement, par exemple une page Login. Configurez la règle de stratégie de sécurité Google Cloud Armor pour rediriger la requête vers la page de test reCAPTCHA lorsque le score est faible.

L'illustration suivante montre un workflow qui utilise les fonctionnalités de page de test reCAPTCHA et de jeton de session reCAPTCHA :

Exemple 2 : Utiliser la page de test reCAPTCHA et les jetons d'action reCAPTCHA

Vous pouvez ajouter un jeton d'action reCAPTCHA pour protéger une action utilisateur, telle que le paiement. Configurez la règle de stratégie de sécurité Google Cloud Armor pour rediriger la requête vers la page d'authentification reCAPTCHA selon l'une des conditions suivantes :

  • Le score est faible.
  • L'attribut action_name du jeton d'action ne correspond pas à l'action utilisateur protégée.

L'illustration suivante montre un workflow qui utilise les fonctionnalités de page de test reCAPTCHA et de jeton d'action reCAPTCHA :

L'exemple de script suivant montre comment utiliser un jeton d'action reCAPTCHA et rediriger vers la page du défi reCAPTCHA avec le jeton d'action associé en tant qu'en-tête :

   <script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY_ACTION_TOKEN_ENABLED"></script>
    <script>
     function onSuccess(token) {
       const xhr = new XMLHttpRequest();
       xhr.open('GET','http://www.abc.com/checkout', false);
       xhr.setRequestHeader("X-Recaptcha-Token", token);
       xhr.onreadystatechange = function() {
         // Make sure that the request is finished and response is ready with 200
         if (this.readyState == 4 && this.status == 200) {
           // Display the response, it could be the reCAPTCHA challenge
           // page based on your Google Cloud Armor security rule settings.
            document.open();
            document.write(xhr.responseText);
            document.close();

         }
       };
       xhr.send(null);
     }

     grecaptcha.enterprise.ready(function () {
       document.getElementById("execute-button").onclick = () => {
         grecaptcha.enterprise.execute('SITE_KEY_ACTION_TOKEN_ENABLED', {
         }).then(onSuccess, onError);
       };
     });
    </script>

Étape suivante