API de Seguridad

La API de Seguridad proporciona herramientas para proteger el tenant contra accesos no autorizados y actividad maliciosa. Los administradores pueden mantener listas de IP permitidas/bloqueadas, revisar eventos de inicio de sesión sospechosos, configurar la verificación CAPTCHA y gestionar bloqueos de cuentas.

Auris evalúa las reglas de seguridad durante cada intento de autenticación en este orden: reglas de IP (bloquear/permitir) -> verificación CAPTCHA -> limitación de tasa -> validación de credenciales -> análisis de inicio de sesión sospechoso -> MFA adaptativo. Cada capa opera de forma independiente y puede configurarse por separado.

Reglas de IP

Las reglas de IP definen listas de permitidos y bloqueados usando notación CIDR. Las reglas de bloqueo siempre tienen precedencia sobre las reglas de permitido. Las reglas pueden tener alcance para todo el tenant o para una aplicación específica.

Listar Reglas de IP

GET/api/ip-rulesRequires: manage:users

Lista todas las reglas de IP de permitidos/bloqueados configuradas para el tenant. Admite filtrado por tipo de regla, alcance y estado activo. Las reglas se ordenan por fecha de creación descendente.

Parámetros de consulta

Parámetro	Tipo	Descripción
`type`	string	Filtrar por tipo de regla: `ALLOW` o `BLOCK`
`scope`	string	Filtrar por alcance: `TENANT` o `APPLICATION`
`isActive`	boolean	Filtrar por estado activo
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20, máx.: 100)

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "ipr_abc123",
        "cidr": "203.0.113.0/24",
        "type": "BLOCK",
        "scope": "TENANT",
        "applicationId": null,
        "label": "Known bad actor range",
        "note": "Blocked after brute-force campaign on 2025-02-10",
        "isTemporary": true,
        "expiresAt": "2025-03-10T00:00:00Z",
        "isActive": true,
        "createdAt": "2025-02-10T14:30:00Z",
        "updatedAt": "2025-02-10T14:30:00Z"
      },
      {
        "id": "ipr_def456",
        "cidr": "10.0.0.0/8",
        "type": "ALLOW",
        "scope": "TENANT",
        "applicationId": null,
        "label": "Corporate VPN",
        "note": "Internal network range",
        "isTemporary": false,
        "expiresAt": null,
        "isActive": true,
        "createdAt": "2025-01-15T09:00:00Z",
        "updatedAt": "2025-01-15T09:00:00Z"
      },
      {
        "id": "ipr_ghi789",
        "cidr": "198.51.100.50/32",
        "type": "BLOCK",
        "scope": "APPLICATION",
        "applicationId": "app_prod001",
        "label": "Suspicious IP",
        "note": null,
        "isTemporary": false,
        "expiresAt": null,
        "isActive": true,
        "createdAt": "2025-02-05T11:20:00Z",
        "updatedAt": "2025-02-05T11:20:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1
    }
  }
}

Crear Regla de IP

POST/api/ip-rulesRequires: manage:users

Crea una nueva regla de IP de permitido o bloqueo. Se requiere notación CIDR — usa /32 para una única dirección IP. Las reglas de bloqueo siempre tienen precedencia sobre las reglas de permitido durante la evaluación.

Cuerpo de la solicitud


{
  "cidr": "192.0.2.0/24",
  "type": "BLOCK",
  "scope": "TENANT",
  "label": "Datacenter range",
  "note": "Blocked due to automated scraping activity",
  "isTemporary": true,
  "expiresAt": "2025-04-01T00:00:00Z"
}

Campo	Tipo	Requerido	Descripción
`cidr`	string	Sí	Dirección IP o rango en notación CIDR (p. ej., `10.0.0.1/32`, `192.168.0.0/16`)
`type`	string	Sí	`ALLOW` o `BLOCK`
`scope`	string	Sí	`TENANT` (aplica a todas las apps) o `APPLICATION` (requiere `applicationId`)
`applicationId`	string	No	Requerido cuando el alcance es `APPLICATION`
`label`	string	No	Etiqueta legible para la regla
`note`	string	No	Nota administrativa o razón
`isTemporary`	boolean	No	Si la regla expira automáticamente (por defecto: `false`)
`expiresAt`	string	No	Fecha de expiración ISO 8601. Requerido cuando `isTemporary` es `true`

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "ipr_jkl012",
    "cidr": "192.0.2.0/24",
    "type": "BLOCK",
    "scope": "TENANT",
    "applicationId": null,
    "label": "Datacenter range",
    "note": "Blocked due to automated scraping activity",
    "isTemporary": true,
    "expiresAt": "2025-04-01T00:00:00Z",
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Notación CIDR inválida, campos requeridos faltantes o combinación de alcance/tipo inválida
`DUPLICATE_RULE`	409	Ya existe una regla con el mismo CIDR y alcance

Las reglas temporales se limpian automáticamente después de su timestamp expiresAt. No es necesario eliminarlas manualmente.

Actualizar Regla de IP

PATCH/api/ip-rules/[id]Requires: manage:users

Actualiza una regla de IP existente. Todos los campos son opcionales — solo se actualizan los campos proporcionados. Cambiar el CIDR o el tipo de una regla tiene efecto inmediato para los intentos de inicio de sesión posteriores.

Cuerpo de la solicitud


{
  "label": "Updated label",
  "note": "Extended block after continued activity",
  "isActive": false
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "ipr_abc123",
    "cidr": "203.0.113.0/24",
    "type": "BLOCK",
    "scope": "TENANT",
    "applicationId": null,
    "label": "Updated label",
    "note": "Extended block after continued activity",
    "isTemporary": true,
    "expiresAt": "2025-03-10T00:00:00Z",
    "isActive": false,
    "createdAt": "2025-02-10T14:30:00Z",
    "updatedAt": "2025-02-18T10:30:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	La regla de IP no existe
`VALIDATION_ERROR`	400	Valor de campo inválido

Eliminar Regla de IP

DELETE/api/ip-rules/[id]Requires: manage:users

Elimina permanentemente una regla de IP. La regla se elimina inmediatamente y ya no será evaluada durante los intentos de autenticación.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "deleted": true,
    "id": "ipr_abc123"
  }
}

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	La regla de IP no existe

Eventos de Inicio de Sesión Sospechosos

Auris monitorea los intentos de inicio de sesión para detectar comportamientos anómalos usando cinco métodos de detección: nuevo dispositivo, nueva dirección IP, nuevo país, viaje imposible y uso de VPN/proxy. Cuando se detecta actividad sospechosa, se registra un evento y se toma la acción configurada (solo registrar, requerir MFA o bloquear).

Listar Eventos de Inicio de Sesión Sospechosos

GET/api/suspicious-login/eventsRequires: manage:users

Lista eventos de inicio de sesión sospechosos en todo el tenant. Los eventos se ordenan por fecha de creación descendente. Usa el filtro reviewed para encontrar eventos que requieren atención del administrador.

Parámetros de consulta

Parámetro	Tipo	Descripción
`userId`	string	Filtrar eventos para un usuario específico
`severity`	string	Filtrar por severidad: `low`, `medium`, `high`, `critical`
`reason`	string	Filtrar por razón de detección: `new_device`, `new_ip`, `new_country`, `impossible_travel`, `vpn_detected`
`reviewed`	boolean	`true` para eventos revisados, `false` para no revisados
`page`	integer	Número de página (por defecto: 1)
`limit`	integer	Elementos por página (por defecto: 20, máx.: 100)

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "sle_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "reason": "impossible_travel",
        "severity": "high",
        "actionTaken": "require_mfa",
        "details": {
          "previousLocation": { "country": "Italy", "city": "Rome", "lat": 41.9028, "lng": 12.4964 },
          "currentLocation": { "country": "Brazil", "city": "Sao Paulo", "lat": -23.5505, "lng": -46.6333 },
          "distanceKm": 9187,
          "timeDiffMinutes": 45,
          "requiredSpeedKmh": 12249
        },
        "ipAddress": "198.51.100.42",
        "reviewed": false,
        "reviewedAt": null,
        "reviewedBy": null,
        "createdAt": "2025-02-18T09:15:00Z"
      },
      {
        "id": "sle_def456",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "reason": "vpn_detected",
        "severity": "medium",
        "actionTaken": "log",
        "details": {
          "ipAddress": "203.0.113.50",
          "isp": "NordVPN",
          "isVpn": true,
          "isProxy": false,
          "isDatacenter": true
        },
        "ipAddress": "203.0.113.50",
        "reviewed": true,
        "reviewedAt": "2025-02-18T10:00:00Z",
        "reviewedBy": "usr_admin001",
        "createdAt": "2025-02-18T08:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 47,
      "totalPages": 3
    }
  }
}

Marcar Evento como Revisado

PATCH/api/suspicious-login/events/[id]/reviewRequires: manage:users

Marca un evento de inicio de sesión sospechoso como revisado. Esto es un reconocimiento administrativo y no afecta el acceso del usuario. Úsalo para llevar un registro de qué eventos han sido investigados.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "id": "sle_abc123",
    "reviewed": true,
    "reviewedAt": "2025-02-18T11:00:00Z",
    "reviewedBy": "usr_admin001"
  }
}

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	El evento no existe
`ALREADY_REVIEWED`	400	El evento ya fue marcado como revisado

Obtener Configuración de Detección

GET/api/suspicious-login/configRequires: manage:users

Recupera la configuración actual de detección de inicios de sesión sospechosos para el tenant.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "detectNewDevice": true,
    "detectNewIp": true,
    "detectNewCountry": true,
    "detectImpossibleTravel": true,
    "detectVpn": false,
    "actionOnNewDevice": "log",
    "actionOnNewIp": "log",
    "actionOnNewCountry": "require_mfa",
    "actionOnImpossibleTravel": "require_mfa",
    "actionOnVpn": "log",
    "maxTravelSpeedKmh": 900,
    "geoIpProvider": "ip-api",
    "updatedAt": "2025-02-01T12:00:00Z"
  }
}

Campo	Tipo	Descripción
`detectNewDevice`	boolean	Marcar inicios de sesión desde huellas de dispositivo no vistas anteriormente
`detectNewIp`	boolean	Marcar inicios de sesión desde direcciones IP no vistas anteriormente
`detectNewCountry`	boolean	Marcar inicios de sesión desde un nuevo país
`detectImpossibleTravel`	boolean	Marcar cuando los inicios de sesión consecutivos son geográficamente imposibles dado el tiempo transcurrido
`detectVpn`	boolean	Marcar inicios de sesión desde IPs conocidas de VPN/proxy/datacenter
`actionOn*`	string	Acción a tomar: `log` (solo registrar), `require_mfa` (forzar 2FA), `block` (denegar acceso)
`maxTravelSpeedKmh`	integer	Umbral de velocidad para la detección de viaje imposible (por defecto: 900 km/h)

Actualizar Configuración de Detección

PATCH/api/suspicious-login/configRequires: manage:users

Actualiza la configuración de detección de inicios de sesión sospechosos. Todos los campos son opcionales. Los cambios tienen efecto inmediato para los intentos de inicio de sesión posteriores.

Cuerpo de la solicitud


{
  "detectVpn": true,
  "actionOnVpn": "require_mfa",
  "actionOnImpossibleTravel": "block",
  "maxTravelSpeedKmh": 1000
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "detectNewDevice": true,
    "detectNewIp": true,
    "detectNewCountry": true,
    "detectImpossibleTravel": true,
    "detectVpn": true,
    "actionOnNewDevice": "log",
    "actionOnNewIp": "log",
    "actionOnNewCountry": "require_mfa",
    "actionOnImpossibleTravel": "block",
    "actionOnVpn": "require_mfa",
    "maxTravelSpeedKmh": 1000,
    "geoIpProvider": "ip-api",
    "updatedAt": "2025-02-18T11:30:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Valor de acción inválido o `maxTravelSpeedKmh` fuera de rango (100-5000)

Establecer actionOnImpossibleTravel o actionOnNewCountry en block puede bloquear a usuarios legítimos que viajan frecuentemente o usan redes móviles. Considera usar require_mfa en su lugar, que agrega un paso de verificación sin denegar el acceso por completo.

CAPTCHA

La verificación CAPTCHA agrega un desafío humano a los flujos de autenticación. Auris admite tres proveedores: Cloudflare Turnstile, hCaptcha y reCAPTCHA v3. El CAPTCHA puede activarse en cada intento, solo después de actividad sospechosa, o después de un número configurable de intentos de inicio de sesión fallidos.

Obtener Configuración de CAPTCHA

GET/api/captcha/configRequires: manage:users

Recupera la configuración actual de CAPTCHA para el tenant.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "provider": "CLOUDFLARE_TURNSTILE",
    "trigger": "ON_SUSPICIOUS",
    "siteKey": "0x4AAAAAAA...",
    "scoreThreshold": 0.5,
    "enableOnLogin": true,
    "enableOnRegister": true,
    "enableOnReset": false,
    "updatedAt": "2025-02-15T10:00:00Z"
  }
}

La secretKey nunca se devuelve en las respuestas de la API. Solo puede establecerse mediante el endpoint de actualización.

Actualizar Configuración de CAPTCHA

PATCH/api/captcha/configRequires: manage:users

Actualiza la configuración de CAPTCHA. Todos los campos son opcionales. Establece provider como null para deshabilitar CAPTCHA por completo. El siteKey y el secretKey deben ser válidos para el proveedor seleccionado.

Cuerpo de la solicitud


{
  "provider": "CLOUDFLARE_TURNSTILE",
  "trigger": "AFTER_FAILURES",
  "siteKey": "0x4AAAAAAA_your_site_key",
  "secretKey": "0x4AAAAAAA_your_secret_key",
  "scoreThreshold": 0.5,
  "enableOnLogin": true,
  "enableOnRegister": true,
  "enableOnReset": true
}

Campo	Tipo	Descripción
`provider`	string	`CLOUDFLARE_TURNSTILE`, `HCAPTCHA`, `RECAPTCHA_V3`, o `null` para deshabilitar
`trigger`	string	`ALWAYS` (cada intento), `ON_SUSPICIOUS` (tras detectar actividad sospechosa), `AFTER_FAILURES` (tras N inicios de sesión fallidos)
`siteKey`	string	Clave pública del proveedor CAPTCHA
`secretKey`	string	Clave secreta del proveedor CAPTCHA (solo escritura, nunca se devuelve)
`scoreThreshold`	number	Umbral de puntuación para reCAPTCHA v3 (0.0 - 1.0, por defecto: 0.5). Ignorado para otros proveedores
`enableOnLogin`	boolean	Habilitar CAPTCHA en la página de inicio de sesión
`enableOnRegister`	boolean	Habilitar CAPTCHA en la página de registro
`enableOnReset`	boolean	Habilitar CAPTCHA en la página de restablecimiento de contraseña

Respuesta exitosa


{
  "ok": true,
  "data": {
    "provider": "CLOUDFLARE_TURNSTILE",
    "trigger": "AFTER_FAILURES",
    "siteKey": "0x4AAAAAAA_your_site_key",
    "scoreThreshold": 0.5,
    "enableOnLogin": true,
    "enableOnRegister": true,
    "enableOnReset": true,
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Códigos de error

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Proveedor inválido, siteKey/secretKey faltante cuando el proveedor está establecido, o scoreThreshold fuera de rango

Bloqueos de Cuentas

Cuando un usuario supera el lockoutThreshold configurado en la configuración de seguridad, su cuenta se bloquea temporalmente. Los administradores pueden ver las cuentas bloqueadas y desbloquearlas manualmente.

Listar Cuentas Bloqueadas

GET/api/admin/lockoutsRequires: manage:users

Lista todas las cuentas de usuario actualmente bloqueadas. Solo se devuelven las cuentas con bloqueos activos. Los bloqueos que han expirado naturalmente no se incluyen.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "lock_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Smith",
        "failedAttempts": 5,
        "lockedAt": "2025-02-18T09:00:00Z",
        "expiresAt": "2025-02-18T09:15:00Z",
        "ipAddress": "203.0.113.50"
      },
      {
        "id": "lock_def456",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "userName": "Bob Jones",
        "failedAttempts": 5,
        "lockedAt": "2025-02-18T08:50:00Z",
        "expiresAt": "2025-02-18T09:05:00Z",
        "ipAddress": "198.51.100.42"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    }
  }
}

Desbloquear Cuenta

DELETE/api/admin/lockouts/[userId]Requires: manage:users

Desbloquea inmediatamente una cuenta de usuario. El contador de intentos fallidos se restablece a cero. El usuario puede intentar iniciar sesión de nuevo inmediatamente después de ser desbloqueado.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "unlocked": true,
    "userId": "usr_xyz789"
  }
}

Códigos de error

Código	HTTP	Descripción
`NOT_FOUND`	404	El usuario no está actualmente bloqueado

Los bloqueos de cuentas expiran automáticamente según el lockoutDuration configurado en la configuración de seguridad. El desbloqueo manual solo es necesario cuando un usuario legítimo está bloqueado y no puede esperar a que expire el bloqueo.

Orden de Evaluación de Seguridad

Durante cada intento de autenticación, Auris evalúa las capas de seguridad en este orden:

Reglas de IP — Si la IP del cliente coincide con una regla BLOCK, la solicitud se deniega inmediatamente con 403 IP_BLOCKED.
CAPTCHA — Si CAPTCHA está configurado y se cumple la condición de activación, el cliente debe proporcionar un token CAPTCHA válido.
Limitación de Tasa — Se verifican los límites de tasa de ventana deslizante (configurables por nivel).
Validación de Credenciales — Verificación de usuario/contraseña u otras credenciales a través de Keycloak.
Fuerza Bruta / Bloqueo — El contador de intentos fallidos se incrementa. Si se alcanza el umbral, la cuenta se bloquea.
Análisis de Inicio de Sesión Sospechoso — Análisis post-autenticación del dispositivo, IP, geografía y patrones de viaje.
MFA Adaptativo — La puntuación de riesgo puede activar la autenticación de paso adicional si supera los umbrales.

Cada capa es independiente y puede deshabilitarse sin afectar a las demás.

Referencia de Permisos

Permiso	Descripción
`manage:users`	Gestionar reglas de IP, revisar eventos de inicio de sesión sospechosos, configurar CAPTCHA y desbloquear cuentas

Las operaciones de gestión de seguridad se agrupan bajo el permiso manage:users. Esto garantiza que solo los administradores con acceso completo de gestión de usuarios puedan modificar la configuración de seguridad que afecta la autenticación de todos los usuarios en el tenant.

Relacionado

MFA Adaptativo y Puntuación de Riesgo — Cómo la puntuación de riesgo impulsa las decisiones de seguridad
Protección contra Ataques — Configura protección contra fuerza bruta e inicios de sesión sospechosos
Configuración de Protección contra Amenazas — Reglas de IP, CAPTCHA y detección de bots
Configuración de Seguridad — Gestiona todas las funciones de seguridad desde la Consola
Puntuación de Riesgo y MFA Adaptativo — Configura reglas y umbrales de riesgo