Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Configura las políticas de desafío

En este documento, se explica cómo configurar políticas de desafío con una integración existente de Google Cloud Fraud Defense.

Las políticas de verificación te permiten activar de forma selectiva los desafíos de CAPTCHA según reglas personalizadas. Estas reglas deciden cuándo mostrar un desafío de Fraud Defense en función de las puntuaciones de riesgo, las direcciones IP, los usuarios-agentes, los ASN, las regiones geográficas o las identidades de bots (agentes de IA) verificadas.

Puedes usar las políticas de desafío con las siguientes funciones recomendadas:

Configuración de AutoExecute: Simplifica la integración de JavaScript para las aplicaciones cliente.
Desafíos: Activa la verificación del usuario cuando lo requieran las reglas de desafío. Fraud Defense admite los siguientes tipos de desafíos:
- Desafíos visuales: Pide a los usuarios que seleccionen imágenes según una instrucción. De forma predeterminada, se selecciona un desafío visual cuando se configura una regla con la opción de desafío seleccionada.
- Desafíos de audio: Pide a los usuarios que identifiquen indicaciones de audio hablado como una alternativa de accesibilidad.
- Desafíos de códigos QR: Pide a los usuarios que escaneen un código QR con su dispositivo móvil para resolver un desafío. Tu clave universal debe estar en una lista de entidades permitidas para usar esta función. Para agregar tu clave universal a la lista de entidades permitidas, comunícate con el equipo de Defensa contra fraudes en fraud-defense@google.com y proporciona tu clave universal.

Antes de comenzar

Prepara tu entorno para Google Cloud Fraud Defense.
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud . Puedes habilitar la facturación con una tarjeta de crédito o un ID de facturación del proyecto de Google Cloud existente. Si necesitas ayuda con la facturación, comunícate con el equipo de asistencia de Facturación de Cloud.
Crea o identifica una clave universal para tu proyecto. Para crear una clave, consulta Crea una clave universal. Como alternativa, puedes copiar el ID de una clave universal existente completando uno de los siguientes pasos:
- Para copiar el ID de una clave existente desde la consola de Google Cloud , haz lo siguiente:
  1. En la consola de Google Cloud , ve a la página Google Cloud Fraud Defense.
    
    Ir a Fraud Defense
  2. En la lista Claves, busca la clave que quieres copiar y haz clic en Copiar en el portapapeles.
- Para copiar el ID de una clave existente con la API de REST, llama al método projects.keys.list.
- Para copiar el ID de una clave existente con gcloud CLI, ejecuta el comando gcloud recaptcha keys list.
Planifica tu integración de Fraud Defense identificando las acciones del usuario que deseas proteger (como login, signup o password_reset) y qué páginas de tu sitio web activan estas acciones. Si usas la configuración de AutoExecute, asegúrate de que estas acciones sean coherentes con los nombres de las acciones especificados en el protected_endpoint_group.
Integra Fraud Defense en tu página web. Te recomendamos que uses la configuración de ejecución automática de Fraud Defense. Para obtener instrucciones generales de configuración, consulta Instala llaves universales en sitios web.

Descripción general de la configuración de la política de Fraud Defense

La configuración de la política de Fraud Defense te permite personalizar el comportamiento de la protección de Fraud Defense. Puedes configurar las políticas de desafío con la sección challenge_rule_groups.

Puedes ver y actualizar la configuración de la política con la consola de Google Cloud , gcloud CLI o la API de REST de reCAPTCHA Enterprise.

Console

Para ver o actualizar la configuración de la política en la consola de Google Cloud , haz lo siguiente:

En la consola de Google Cloud , ve a la página Fraud Defense.

Ir a Fraud Defense
Asegúrate de que tu proyecto esté seleccionado en el selector de recursos.
En la tabla Claves de reCAPTCHA, haz clic en el nombre de la clave para la que deseas configurar las políticas de desafío.
En la página Detalles de la clave, ve a la pestaña Política.
En la sección Grupos de reglas, puedes ver, agregar o editar tus reglas de desafío y expresiones de condición.
Haz clic en Guardar.

gcloud

Para actualizar la configuración de la política de una clave, ejecuta el comando gcloud alpha recaptcha policies update:

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

Para ver la configuración de la política actual de una clave, ejecuta el comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

API de REST

Para actualizar la configuración de la política de una clave, llama al método projects.keys.updatePolicy:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

Para ver la configuración de la política actual de una clave, llama al método projects.keys.getPolicy:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

La configuración de la política usa el formato YAML para Google Cloud CLI y el formato JSON para la API de REST. Para ver el esquema completo de la sección challenge_rule_groups, consulta Configura políticas de desafío.

Para ver ejemplos de diferentes casos de uso, consulta Ejemplos de configuraciones de reglas de desafío.

Configura políticas de desafío

Las políticas de desafío se configuran en la sección challenge_rule_groups de la configuración de la política de Fraud Defense. Si ya tienes una política con client_settings, incluida la información de los dominios, puedes actualizar la política para incluir las reglas de la política de desafío.

La sección challenge_rule_groups tiene la siguiente estructura:

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

En cada regla de desafío, el campo condition es opcional. Si condition no se especifica o está vacío, la regla se aplica de forma incondicional. Además, los campos challenge y no_challenge son mutuamente excluyentes, y exactamente uno de ellos debe estar presente en cada regla.

Orden de evaluación de reglas

Los grupos de reglas y sus reglas internas se evalúan de forma secuencial de arriba abajo. Se aplica la primera regla coincidente. Cuando ningún grupo ni ninguna regla coinciden con la interacción, la evaluación se establece de forma predeterminada en la evaluación estándar sin que se muestre ningún desafío, pero se genera una puntuación de riesgo para la solicitud.

Niveles de dificultad de los desafíos

Puedes especificar el nivel de dificultad cuando actives un desafío. Para obtener una lista completa de los valores de dificultad válidos, consulta la referencia de la API de ChallengeSecurityPreference.

Sintaxis de la condición

El campo condition es una cadena opcional con formato de expresión de Common Expression Language (CEL). Si condition no se especifica o está vacío, la regla se aplica de forma incondicional. CEL proporciona operadores estándar similares a C, incluidos los operadores relacionales (<, <=, >, >=, ==, !=), aritméticos (+, -, /, *, %), lógicos (!, &&, ||) y de contenedor ([], in). CEL admite tipos de datos primitivos comunes (bool, int, uint, double, string), tipos de contenedores básicos (lists, messages) y constantes (como true, 1, 0.5, "hello" y [1, 2, 3]).

En el entorno de ejecución, se puede acceder a las siguientes variables de Fraud Defense:

Variable	Tipo	Descripción
`score`	`double`	La puntuación de bot de Fraud Defense.
`user_ip_address`	`string`	La dirección IP (IPv4 o IPv6) del usuario que realiza la solicitud.
`user_agent`	`string`	Es el usuario-agente del usuario que realiza la solicitud.
`user_asn`	`int`	Es el número de sistema autónomo (ASN) del usuario que realiza la solicitud. Omite el prefijo `AS` (por ejemplo, usa `12345` en lugar de `AS12345`).
`region_code`	`string`	Es el código de región CLDR de Unicode (basado en ISO 3166-1 alfa-2) asociado con la ubicación de la solicitud (por ejemplo, `"US"`, `"CA"` o `"FR"`).
`verified_bots`	`list(Bot)`	Es una lista de rastreadores o agentes automatizados verificados (como indexadores de motores de búsqueda, asistentes de búsqueda con IA y scrapers de contenido de socios) que identificó Fraud Defense.

Se definen los siguientes tipos adicionales no primitivos. Para obtener la lista completa de valores, consulta Bot.

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

Para obtener más información sobre los posibles valores de name, consulta la referencia de la API de Bot. Para obtener más información sobre los valores de enumeración bot_type válidos, consulta la referencia de la API de BotType.

En las políticas de desafío de Fraud Defense, puedes usar cualquiera de estas variables para producir una expresión booleana. Por ejemplo, score > 0.5, user_ip_address == "192.0.2.1", region_code == "US" y user_asn == 12345 son expresiones de condición válidas que se evalúan como un valor booleano. Ten en cuenta que, debido a que user_asn es un tipo de número entero, debes omitir el prefijo AS cuando verifiques los ASN.

Las siguientes funciones están disponibles para usarse en las condiciones de la política de desafío de Fraud Defense:

Nombre	Firma	Descripción
`contains`	`string.contains(string) -> bool`	Verifica si el operando de cadena contiene la subcadena.
`startsWith`	`string.startsWith(string) -> bool`	Verifica si el operando de cadena comienza con el prefijo especificado.
`endsWith`	`string.endsWith(string) -> bool`	Verifica si el operando de cadena termina con el sufijo especificado.
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	Devuelve el tamaño de una cadena (cantidad de puntos de código) o una lista (cantidad de elementos).

Las funciones de comprensión son un estilo de macro integrado en CEL. Están disponibles las siguientes comprensiones:

Nombre	Firma	Descripción	Ejemplo
`has`	`has(message.field) -> bool`	Verifica si un campo está disponible.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Verifica si todos los elementos `x` de una lista `e` coinciden con el predicado `p`.	`[1, 2, 3].all(x, x > 0)`
`exists`	`list(A).exists(A, predicate(A) -> bool) -> bool`	Verifica si algún elemento `x` de una lista `e` coincide con el predicado `p`.	`[1, 2, 3].exists(i, i % 2 != 0)`
`exists_one`	`list(A).exists_one(A, predicate(A)) -> bool`	Verifica si exactamente un elemento `x` de una lista `e` coincide con el predicado `p`.	`[1, 2, 2].exists_one(i, i < 2)`

Ejemplos de configuraciones de reglas de desafío

En esta sección, se incluyen ejemplos de configuración de reglas de desafío válidas.

Desafía todas las solicitudes que tengan una puntuación baja

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Selecciona un desafío de alta fricción para todas las solicitudes con una puntuación baja

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

Cuestiona las acciones específicas que tengan una puntuación baja.

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

Configura diferentes umbrales de reglas para diferentes acciones

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

No mostrar el desafío a las direcciones IP de la lista de entidades permitidas

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

Nota: Esta regla es distinta de la función Listas de IPs permitidas de Fraud Defense.

No mostrar el desafío a la subred de direcciones IP

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

No mostrar el desafío a las solicitudes de ASNs específicos

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

No mostrar el desafío a un agente de Google

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

Mostrar un desafío basado en condiciones complejas

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

¿Qué sigue?

Para evaluar el token de respuesta de reCAPTCHA, consulta Crea evaluaciones para sitios web.