Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 desafío te permiten activar de forma selectiva los desafíos de CAPTCHA en función de 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 o las identidades de bots verificados (agentes de IA).

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

Configuración de AutoExecute: Simplifica la integración de JavaScript para aplicaciones cliente.
Desafíos: Activa la verificación del usuario cuando lo requieren tus reglas de desafío. Fraud Defense admite los siguientes tipos de desafíos:
- Desafíos visuales: Pídeles a los usuarios que seleccionen imágenes en función de 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: Pídeles a los usuarios que identifiquen indicaciones de audio habladas como una alternativa de accesibilidad.
- Desafíos de código QR: Pídeles 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 Fraud Defense a 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 Google Cloud proyecto. Puedes habilitar la facturación con una tarjeta de crédito o un ID de facturación de proyecto existente Google Cloud . 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 Google Cloud consola, haz lo siguiente:
  1. En la Google Cloud consola, ve a la página Google Cloud Fraud Defense.
    
    Ir a Fraud Defense
  2. En la lista Claves de reCAPTCHA, busca la clave que deseas copiar y haz clic en Copiar al portapapeles.
- Para copiar el ID de una clave existente con la API de REST, llama al projects.keys.list método.
- Para copiar el ID de una clave existente con gcloud CLI, ejecuta el gcloud recaptcha keys list comando.
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 acción especificados en el protected_endpoint_group.
Integra Fraud Defense en tu página web. Te recomendamos que uses la configuración de AutoExecute de Fraud Defense. Para obtener instrucciones de configuración generales, consulta Instala claves universales en sitios web.

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

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

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

Console

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

En la Google Cloud consola, 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 políticas de una clave, ejecuta el gcloud alpha recaptcha policies update comando:

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

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

gcloud alpha recaptcha policies describe --key=KEY_ID

API de REST

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

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 políticas actual de una clave, llama al projects.keys.getPolicy método:

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

La configuración de políticas usa el formato YAML para Google Cloud CLI y el formato JSON para la API de REST. Para obtener 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

Configuras las políticas de desafío dentro de la sección challenge_rule_groups de la configuración de políticas 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 tus reglas de 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 no se especifica condition 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 del desafío

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

Sintaxis de las condiciones

El campo condition es una cadena opcional con formato de expresión de Common Expression Language (CEL). Si no se especifica condition o está vacío, la regla se aplica de forma incondicional. CEL proporciona operadores estándar similares a C, incluidos 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]).

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

Variable	Tipo	Descripción
`score`	`double`	La puntuación del bot de Fraud Defense.
`user_ip_address`	`string`	La dirección IP (IPv4 o IPv6) del usuario que realiza la solicitud.
`user_agent`	`string`	El usuario-agente del usuario que realiza la solicitud.
`user_asn`	`int`	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`).
`verified_bots`	`list(Bot)`	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 Fraud Defense identificó.

Se definen los siguientes tipos no primitivos adicionales. 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 valores name posibles, consulta la referencia de la API de Bot. Para obtener más información sobre los valores enum 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" y user_asn == 12345 son expresiones de condición válidas que se evalúan como booleanas. Ten en cuenta que, como user_asn es un tipo entero, debes omitir el prefijo AS cuando verificas los ASN.

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

Nombre	Firma	Descripción
`contains`	`string.contains(string) -> bool`	Comprueba si el operando de cadena contiene la substring.
`startsWith`	`string.startsWith(string) -> bool`	Comprueba si el operando de cadena comienza con el prefijo especificado.
`endsWith`	`string.endsWith(string) -> bool`	Comprueba si el operando de cadena termina con el sufijo especificado.
`size`	`size(string) -> int` `size(list) -> int` `string.size() -> int` `list.size() -> int`	Muestra 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 integrada en CEL. Las siguientes comprensiones están disponibles:

Nombre	Firma	Descripción	Ejemplo
`has`	`has(message.field) -> bool`	Comprueba si un campo está disponible.	`has(verified_bots[0].name)`
`all`	`list(A).all(A, predicate(A) -> bool) -> bool`	Comprueba 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`	Comprueba 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`	Comprueba 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'

Desafía 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 desafío a las direcciones IP en 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 de listas de entidades permitidas de IP de Fraud Defense.

No mostrar 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 desafío a las solicitudes de ASN 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 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 desafío en función de 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.