Cómo implementar las funciones de integración de reCAPTCHA Enterprise para WAF y Google Cloud Armor

En este documento, se muestra cómo implementar la página de desafío de reCAPTCHA, los tokens de acción de reCAPTCHA y los tokens de sesión de reCAPTCHA para Google Cloud Armor.

Antes de comenzar

Para usar tokens de acción o tokens de sesión de reCAPTCHA, habilita la API de reCAPTCHA Enterprise mediante los siguientes pasos:

  1. En Cloud Console, ve a la página API de reCAPTCHA Enterprise.

    Ir a la API de reCAPTCHA Enterprise

  2. Verifica que el nombre de tu proyecto aparezca en el selector de proyectos en la parte superior de la página.

    Si no ves el nombre de tu proyecto, haz clic en el selector de proyecto y, luego, selecciona tu proyecto.

  3. Haga clic en Habilitar.

Cómo implementar la página de desafío de reCAPTCHA

No hay pasos de implementación para la página de desafíos de reCAPTCHA porque reCAPTCHA Enterprise controla la implementación de manera automática.

Como paso siguiente, configura las políticas de seguridad de Google Cloud Armor.

Implementa tokens de acción de reCAPTCHA

Debes tener reCAPTCHA Enterprise en ejecución en tus páginas web para generar tokens de acción. Después de que reCAPTCHA Enterprise genere un token de acción, debes adjuntar el token de acción a un encabezado de solicitud predefinido donde sea necesario para proteger cualquier acción del usuario, como la confirmación de la compra. Según la configuración predeterminada, los tokens de acción son válidos durante 30 minutos y pueden tener una duración menor. Por lo tanto, debes adjuntar el token de acción a un encabezado de solicitud predefinido antes de que caduque para que Google Cloud Armor pueda evaluar los atributos del token.

Para implementar un token de acción de reCAPTCHA, haz lo siguiente:

  1. Crea una nueva clave del sitio basada en la puntuación o con una casilla de verificación de reCAPTCHA.
  2. Si quieres habilitar la función de token de acción para la clave del sitio, envía la clave del sitio a recaptcha-waf-eng@google.com.
  3. Después de habilitar la función de token de acción para la clave del sitio, recibirás un correo electrónico de confirmación.
  4. En sus páginas web, instale la clave del sitio que esté habilitada. Para obtener instrucciones, consulta el documento que corresponde a la clave de tu sitio:

  5. Después de recibir el token de reCAPTCHA Enterprise, adjunta el token a un encabezado de solicitud predefinido en el siguiente formato:

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

    Puedes usar lenguajes como XHR, Ajax y la API de Fetch para adjuntar el token a un encabezado de solicitud predefinido.

En la siguiente secuencia de comandos de ejemplo, se muestra cómo proteger la acción de ejecutar y adjuntar el token a un encabezado de solicitud predefinido con 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>

Como paso siguiente, configura las políticas de seguridad de Google Cloud Armor.

Implementa tokens de sesión de reCAPTCHA

El JavaScript de reCAPTCHA configura un token de sesión de reCAPTCHA como una cookie en el navegador del usuario final después de la evaluación. El navegador del usuario final conecta la cookie y la actualiza siempre que el JavaScript de reCAPTCHA esté activo.

Para proporcionar un token de sesión como una cookie, instala una clave de sitio basada en puntuaciones de reCAPTCHA en al menos una de tus páginas web que cumplan con los siguientes requisitos:

  • La página web debe ser la página que el usuario final explora antes de que sea la página que debe protegerse. Por ejemplo, si quieres proteger la página de confirmación de la compra, instala la clave del sitio basada en la puntuación de reCAPTCHA en la página principal o la de los productos.
  • La página web está protegida por una política de seguridad de Google Cloud Armor.

Puedes usar esta cookie para proteger las solicitudes posteriores y las cargas de página del usuario en un dominio específico. De forma predeterminada, los tokens de sesión son válidos durante 30 minutos. Sin embargo, si el usuario permanece en la página en la que implementaste el token de sesión, reCAPTCHA Enterprise actualiza el token de sesión de forma periódica para evitar que venza.

Instala tokens de sesión en cada página que debe proteger reCAPTCHA Enterprise. Te recomendamos instalar reCAPTCHA Enterprise en todas las páginas y usar las reglas de Google Cloud Armor para aplicar el acceso en todas las páginas, excepto en la primera que exploran los usuarios finales.

A continuación, se muestra un ejemplo de token de sesión de reCAPTCHA:

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

Para implementar un token de sesión de reCAPTCHA, haz lo siguiente:

  1. Crea una clave de sitio nueva basada en la puntuación de reCAPTCHA.
  2. Si quieres habilitar la función de token de sesión para la clave del sitio, envía la clave del sitio a recaptcha-waf-eng@google.com.
  3. Después de habilitar la función de token de sesión para la clave del sitio, recibirás un correo electrónico de confirmación.
  4. Agrega la clave del sitio que está habilitada con la función del token de sesión y waf=session al JavaScript de reCAPTCHA.

La siguiente secuencia de comandos de ejemplo muestra cómo implementar un token de sesión en una página 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>

Como paso siguiente, configura las políticas de seguridad de Google Cloud Armor.

Ejemplos del uso de más de una función en una sola aplicación

Puedes usar una o más funciones de reCAPTCHA Enterprise para WAF en una sola aplicación.

Ejemplo 1: Usa tokens de sesión de reCAPTCHA y la página de desafíos de reCAPTCHA

Puedes agregar un token de sesión de reCAPTCHA en las páginas a las que un usuario podría acceder para que la cookie se actualice periódicamente, por ejemplo, una página Acceso. Configura la regla de la política de seguridad de Google Cloud Armor para que se redireccione la solicitud a la página de desafío de reCAPTCHA cuando la puntuación sea baja.

La siguiente ilustración muestra un flujo de trabajo que usa funciones de página de desafío de reCAPTCHA y token de sesión de reCAPTCHA:

Ejemplo 2: Usa tokens de acción de reCAPTCHA y la página de desafíos de reCAPTCHA

Puedes agregar un token de acción de reCAPTCHA para proteger una acción del usuario, como checkout. Configura la regla de la política de seguridad de Google Cloud Armor para redireccionar la solicitud a la página de desafío de reCAPTCHA en cualquiera de las siguientes condiciones:

  • La puntuación es baja.
  • El atributo action_name del token de acción no coincide con la acción del usuario protegida.

La siguiente ilustración muestra un flujo de trabajo que usa funciones de página de desafío de reCAPTCHA y token de acción de reCAPTCHA:

En la siguiente secuencia de comandos de muestra, se indica cómo usar un token de acción de reCAPTCHA y redireccionar a la página de desafío de reCAPTCHA con el token de acción adjunto como encabezado:

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

¿Qué sigue?