Instalar claves universales en páginas web

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En este documento, se describe cómo puedes instalar e integrar una clave universal en tus páginas web.

Antes de comenzar

1. Prepara tu entorno para Google Cloud Fraud Defense.

2. Crea una clave universal y configura los dominios.

Instala claves universales en tu sitio web

Para instalar tu clave universal y ayudar a proteger tus páginas web, puedes usar la configuración de AutoExecute, la instalación manual de JavaScript o ambos métodos juntos en diferentes extremos con la misma clave universal:

• Configuración de AutoExecute (recomendada): Intercepta automáticamente las solicitudes de red asíncronas a las rutas de URL configuradas y adjunta el token de reCAPTCHA al encabezado de la solicitud.
• Instalación manual: Usa llamadas manuales a grecaptcha.enterprise.execute() o atributos de botones HTML. Puedes usar este método por sí solo o junto con AutoExecute para solicitudes de red que AutoExecute no admite, solicitudes que requieren la colocación de tokens personalizados en la carga útil o durante migraciones incrementales a AutoExecute.

Precaución: No configures AutoExecute ni llamadas manuales a grecaptcha.enterprise.execute() en el mismo extremo. Si lo haces, se activarán solicitudes duplicadas, lo que aumentará la latencia, mostrará desafíos de CAPTCHA duplicados y, posiblemente, generará cargos de evaluación duplicados.

Según tu enfoque de integración, elige la opción adecuada:

Configuración de AutoExecute

AutoExecute puede ayudar a simplificar la integración de JavaScript en el frontend interceptando las solicitudes de red en tus páginas web y eliminando las llamadas manuales a grecaptcha.enterprise.execute() para cada acción del frontend.

Importante: Ten en cuenta lo siguiente cuando uses AutoExecute:

• AutoExecute solo intercepta las solicitudes de red asíncronas iniciadas con la API de Fetch o XMLHttpRequest, incluidas las solicitudes de frameworks como AJAX que usan estas APIs.
• AutoExecute no es compatible con los recursos que se cargan automáticamente cuando se carga la página. En su lugar, aplica AutoExecute a las solicitudes de red activadas por acciones del usuario en la página, como un botón de acceso.
• Para evitar que los desafíos de Fraud Defense causen tiempos de espera de red, aplica tiempos de espera directamente a las solicitudes. Usa AbortSignal.timeout(n) para la API de Fetch y la propiedad XMLHttpRequest.timeout para XMLHttpRequest.

Agrega la etiqueta de secuencia de comandos a tus páginas web

Para cargar Fraud Defense en tu página web, agrega la API de JavaScript con tu clave universal dentro del elemento <head></head> de tu página web:

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

Fraud Defense usa el idioma del navegador de forma predeterminada. Si quieres especificar un idioma diferente, usa el atributo hl=LANG en tu secuencia de comandos. Por ejemplo, para usar el francés, especifica lo siguiente:

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

Para obtener información sobre los idiomas admitidos, consulta los códigos de idioma para Fraud Defense.

Configura extremos protegidos

La secuencia de comandos de Fraud Defense se integra automáticamente en las acciones de red definidas en la configuración de la política de tu clave universal. En esta sección, se define una asignación de rutas de URL (path) a nombres de acciones (action).

Sugerencia: Especifica protected_endpoints solo para rutas de acceso sensibles. Para cada ruta de acceso, especifica un nombre significativo para la interacción del usuario en el parámetro action. Evita proteger todos los extremos, ya que activar Fraud Defense en cada solicitud de backend puede afectar negativamente el rendimiento. Para obtener más orientación, consulta Acciones.

Si la secuencia de comandos de Fraud Defense detecta una solicitud de red asíncrona a una ruta de acceso asignada, intercepta la solicitud, activa una evaluación de riesgos y, posiblemente, muestra un desafío de CAPTCHA al usuario antes de que continúe la solicitud original. El token de respuesta generado se adjunta automáticamente al encabezado X-Recaptcha-Token de la solicitud.

gcloud

Para inspeccionar la configuración de la política actual de tu clave universal, usa el comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Para actualizar la configuración de la política con tus extremos protegidos, crea un archivo YAML (por ejemplo, POLICY.yaml) que defina tus rutas de acceso y acciones protegidas:

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

Actualiza la configuración de la clave con el archivo YAML usando el comando gcloud alpha recaptcha policies update:

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

Nota: El comando gcloud alpha recaptcha policies update actualiza toda la política. Cualquier protected_endpoint_group o challenge_rule_groups existente debe incluirse en tu archivo POLICY.yaml para evitar que se borren.

API de REST

Para actualizar la configuración de la política y definir extremos protegidos con la API de REST, usa el método projects.keys.updatePolicy.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT_ID: Es el ID del proyecto de Google Cloud .
• KEY_ID: Es el ID de tu clave universal.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

Si se realiza correctamente, la solicitud devuelve la configuración de la política actualizada.

Puedes configurar hasta 25 extremos protegidos por clave universal. Cada extremo debe cumplir con los siguientes requisitos:

• action: El nombre de la acción debe contener entre 1 y 100 caracteres, y solo debe usar letras, números, barras (/) y guiones bajos (_).
• path (distingue mayúsculas de minúsculas): La ruta de acceso debe cumplir con los siguientes criterios:
  • Debe ser único, comenzar con / y contener entre 1 y 200 caracteres sin barras diagonales consecutivas (//).
  • Incluye al menos un segmento que no sea comodín (por ejemplo, no puede ser /, /*, /** ni /*/).
  • Los comodines deben ocupar segmentos completos: * coincide con un solo segmento (por ejemplo, /api/*/login o /api/* son válidos; /api/login* no es válido) y ** coincide con varios segmentos solo como el segmento final (por ejemplo, /api/** es válido; /api/**/login no es válido).

Nota: AutoExecute hace coincidir las solicitudes solo en función de la ruta de URL y no verifica el dominio de destino. Esto tiene las siguientes implicaciones prácticas:

• Solicitudes de terceros: Si las herramientas de terceros que se ejecutan en tu página (como las secuencias de comandos de socios o de estadísticas) envían solicitudes a rutas de acceso que coinciden con tus extremos protegidos (por ejemplo, https://analytics.example.net/login que coincide con /login), AutoExecute también las interceptará. Esto puede causar latencia de red adicional, métricas sesgadas o desafíos de CAPTCHA inesperados. Para evitar conflictos, asegúrate de que tus rutas de acceso protegidas sean distintivas (por ejemplo, /auth/v1/login) o usa la instalación manual si se producen colisiones de rutas de acceso.
• APIs entre dominios: Si tu API de backend se aloja en un dominio diferente al de tu sitio web (por ejemplo, examplecdn.net en comparación con www.example.com), AutoExecute funciona automáticamente sin configuración de dominio adicional.

Si la coincidencia con dominios de destino específicos es importante para tu integración, envía una solicitud de función.

En tu backend, obtén el token de respuesta del encabezado de la solicitud X-Recaptcha-Token y crea una evaluación en un plazo de dos minutos.

Importante: Tu backend debe especificar assessment.event.expected_action (o expectedAction en JSON) en CreateAssessmentRequest, y debe coincidir con la acción configurada en ProtectedEndpoint. Por ejemplo, si configuras la acción de extremo protegido como login, tu backend debe establecer expected_action en login cuando crees una evaluación para esa solicitud. Si no hay coincidencia, indica que un atacante está intentando falsificar acciones.

Instalación manual

Te recomendamos que agregues la verificación de Fraud Defense en una interacción del usuario que deba verificarse. Por ejemplo, si deseas verificar la acción de envío de un formulario, debes agregar la verificación de Fraud Defense en la acción de envío.

Según dónde quieras agregar la verificación de Fraud Defense, elige la opción adecuada:

• Agrega la verificación en una interacción del usuario
• Agrega Fraud Defense a un botón HTML

Agrega la verificación en una interacción del usuario

1. Para cargar reCAPTCHA en tu página web, agrega la API de JavaScript con tu clave universal dentro del elemento <head></head> de tu página web:

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

   Fraud Defense usa el idioma del navegador de forma predeterminada. Si quieres especificar un idioma diferente, usa el atributo hl=LANG en tu secuencia de comandos. Por ejemplo, para usar el francés, especifica lo siguiente:

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

   Para obtener información sobre los idiomas admitidos, consulta los códigos de idioma para Fraud Defense.

   Si deseas especificar una ubicación para la insignia, usa badge=LOCATION como parámetro de consulta en la etiqueta de secuencia de comandos. Por ejemplo, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. De forma predeterminada, la ubicación se establece en bottomright. Otros valores posibles son inline y bottomleft.

2. Para agregar la verificación de Fraud Defense en una interacción del usuario, haz lo siguiente:

   1. Para asegurarte de que grecaptcha.enterprise.execute() se ejecute después de que se cargue la biblioteca de Fraud Defense, usa grecaptcha.enterprise.ready().

   2. Llama a grecaptcha.enterprise.execute() en cada interacción que quieras proteger con tu clave universal. Especifica un nombre significativo para una interacción del usuario en el parámetro action. Para obtener más orientación, consulta Acciones.

      Sugerencia: Agrega la llamada a execute a acciones sensibles, como LOGIN, SIGNUP, PASSWORD_RESET o PURCHASE.

      En el siguiente ejemplo, se muestra cómo llamar a grecaptcha.enterprise.execute() en una acción de acceso:

      <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. Después de generar el token, envía el token de reCAPTCHA al backend y crea una evaluación en un plazo de dos minutos.

   Importante: Tu backend debe especificar assessment.event.expected_action (o expectedAction en JSON) en CreateAssessmentRequest, y debe coincidir con la acción configurada en la llamada a execute(). Por ejemplo, si configuras la acción de frontend para que sea LOGIN, el backend debe establecer expected_action en LOGIN cuando se crea una evaluación para esa solicitud. Si no hay coincidencia, indica que un atacante está intentando falsificar acciones.

Agrega Fraud Defense a un botón HTML

1. Para cargar reCAPTCHA en tu página web, agrega la API de JavaScript con tu clave universal en el elemento <head></head> de tu página web:

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

   Fraud Defense usa el idioma del navegador de forma predeterminada. Si quieres especificar un idioma diferente, usa el atributo hl=LANG en tu secuencia de comandos. Por ejemplo, para usar el francés, especifica lo siguiente:

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

   Para obtener información sobre los idiomas admitidos, consulta los códigos de idioma para Fraud Defense.

2. Para agregar Fraud Defense en un botón HTML, haz lo siguiente:

   1. Define una función de devolución de llamada para controlar el token.

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

   Para obtener más información, consulta el método requestSubmit().

   1. Agrega atributos al botón HTML.

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

   Si deseas especificar una ubicación para la insignia, usa el atributo data-badge="LOCATION" en el elemento que tiene class="g-recaptcha". De forma predeterminada, la ubicación se establece en bottomright. Otros valores posibles son inline y bottomleft.

   1. Cuando se usa este botón para enviar un formulario en tu sitio, el parámetro POST g-recaptcha-response contiene el token de respuesta.
   Nota: Si configuras el botón g-recaptcha como disabled, el botón se habilitará cuando se cargue Fraud Defense.

3. Después de generar el token, envía el token de reCAPTCHA al backend y crea una evaluación en un plazo de dos minutos.

   Importante: Tu backend debe especificar assessment.event.expected_action (o expectedAction en JSON) en CreateAssessmentRequest, y debe coincidir con la acción configurada en el botón. Por ejemplo, si configuras la acción del botón como submit, tu backend debe establecer expected_action en submit cuando crees una evaluación para esa solicitud. Si no hay coincidencia, indica que un atacante está intentando falsificar acciones.

¿Qué sigue?

• Para activar desafíos de CAPTCHA basados en reglas personalizadas, configura políticas de desafío.

• Para evaluar el token de respuesta de reCAPTCHA, crea una evaluación.