Motor de Acciones

El Motor de Acciones te permite extender los flujos de autenticación de Auris con código JavaScript personalizado. Las acciones son hooks que se ejecutan en puntos específicos del pipeline de autenticación — antes del inicio de sesión, después del inicio de sesión, antes del registro, etc. — permitiéndote implementar lógica de negocio personalizada sin modificar la plataforma Auris.

Usos habituales de las acciones:

• Agregar datos personalizados a tokens JWT (departamento, nivel de suscripción, feature flags)
• Bloquear inicios de sesión según condiciones de negocio (dominio de email, estado de cuenta en un sistema externo)
• Registrar eventos de autenticación en una plataforma SIEM o analítica externa
• Aplicar validaciones adicionales antes del registro de usuarios
• Integrarse con sistemas de gobernanza de identidad

Disparadores

Las acciones están asociadas a un disparador, que define cuándo se ejecuta la acción en el pipeline de autenticación. Un mismo disparador puede tener múltiples acciones, que se ejecutan en el orden configurado.

Nota: Post-Login es el disparador más utilizado y el mejor punto de partida para la mayoría de los casos de uso (agregar claims, registrar eventos). Usa Pre-Login con moderación, ya que se ejecuta en cada intento de inicio de sesión, incluidos los fallidos, lo que puede afectar al rendimiento bajo carga elevada.

La Lista de Acciones

Ve a Consola → Acciones para ver todas las acciones de tu tenant.

La lista muestra:

Las acciones se ordenan por disparador y orden de ejecución. Dentro del mismo disparador, el número en la columna Orden determina la secuencia de ejecución.

Crear una Acción

Escribir Código de Acción

El Objeto Context

Cada acción recibe un único argumento context. Su estructura depende del disparador:

// estructura de context para el disparador Post-Login
{
  user: {
    id: 'usr_abc123',
    email: '[email protected]',
    emailVerified: true,
    firstName: 'Alice',
    lastName: 'Smith',
    username: 'alice',
    roles: ['editor', 'viewer'],
    metadata: {
      department: 'engineering',
      subscription_tier: 'pro',
    },
    createdAt: '2024-01-15T10:30:00Z',
    lastLoginAt: '2025-02-10T08:15:00Z',
  },
  application: {
    id: 'app_xyz789',
    name: 'Main Web App',
    clientId: 'your-client-id',
    type: 'WEB',
  },
  connection: {
    strategy: 'email-password',  // o 'google', 'github', 'saml', etc.
    name: 'Username-Password-Authentication',
  },
  request: {
    ip: '203.0.113.42',
    userAgent: 'Mozilla/5.0 ...',
    geoip: {
      country: 'IT',
      region: 'Lombardy',
      city: 'Milan',
    },
  },
  tenant: {
    id: 'your-tenant-id',
    name: 'Acme Corp',
  },
}

Para Pre-M2M-Token, el campo user no está presente y en su lugar el context contiene application y scopes (los scopes M2M solicitados).

El Valor de Retorno

Cada acción debe devolver un objeto ActionResult:

type ActionResult = {
  allow: boolean        // Si el flujo de autenticación debe continuar
  message?: string      // Mensaje de error mostrado al usuario si allow: false
  claims?: Record<string, unknown>    // Claims a agregar al JWT
  metadata?: Record<string, unknown>  // Actualizaciones de metadatos del usuario (persistidas)
}

Si tu acción lanza una excepción no controlada, el flujo de autenticación es bloqueado por defecto para fallar de forma segura. Envuelve siempre la lógica que pueda lanzar errores en try/catch si deseas que los fallos no sean bloqueantes.

Acciones de Ejemplo

Bloquear inicio de sesión por dominio de email

// Bloquear inicios de sesión de emails de un dominio competidor
const blockedDomains = ['competitor.com', 'blockeddomain.org']
const emailDomain = context.user.email.split('@')[1]
 
if (blockedDomains.includes(emailDomain)) {
  return {
    allow: false,
    message: 'Tu organización no tiene acceso a esta aplicación.',
  }
}
 
return { allow: true }

Agregar claims personalizados al JWT

// Incluir departamento y nivel de suscripción en cada token
return {
  allow: true,
  claims: {
    department: context.user.metadata?.department || 'general',
    tier: context.user.metadata?.subscription_tier || 'free',
    org_region: context.user.metadata?.region || 'eu',
  },
}

Claim basado en rol

// Establecer un claim 'plan' según el rol del usuario
const roles = context.user.roles || []
 
let plan = 'free'
if (roles.includes('enterprise')) plan = 'enterprise'
else if (roles.includes('pro')) plan = 'pro'
else if (roles.includes('starter')) plan = 'starter'
 
return {
  allow: true,
  claims: { plan },
}

Registrar en un webhook externo (fire-and-forget)

// Registro no bloqueante en un sistema externo
// Usar try/catch para que un fallo del webhook no bloquee el inicio de sesión
try {
  const payload = JSON.stringify({
    event: 'user.login',
    userId: context.user.id,
    email: context.user.email,
    ip: context.request.ip,
    timestamp: new Date().toISOString(),
  })
 
  // Nota: fetch está disponible en el sandbox de la acción
  fetch('https://your-siem.example.com/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-key' },
    body: payload,
  })
} catch (e) {
  // Ignorar silenciosamente los fallos del webhook — no bloquear el inicio de sesión
}
 
return { allow: true }

Bloquear token M2M si el scope no está permitido para esta aplicación

// Pre-M2M-Token: solo permitir el scope 'read:reports' para aplicaciones específicas
const allowedApps = ['app_reporting_service', 'app_analytics']
 
if (context.scopes.includes('read:reports') && !allowedApps.includes(context.application.id)) {
  return {
    allow: false,
    message: 'Esta aplicación no está autorizada a solicitar el scope read:reports.',
  }
}
 
return { allow: true }

Entorno de Ejecución en Sandbox

Las acciones se ejecutan en un sandbox JavaScript restringido. Lo siguiente está disponible:

Lo siguiente está bloqueado y lanzará un error si se usa:

Tiempo Límite

Las acciones tienen un tiempo límite configurable (por defecto: 5000 ms). Si la ejecución supera el tiempo límite, la acción se termina y el flujo de autenticación es bloqueado como si se hubiera devuelto allow: false. Establece un tiempo límite corto para las acciones que realizan llamadas HTTP externas para evitar retrasar la experiencia de inicio de sesión del usuario.

Orden de Ejecución

Cuando múltiples acciones están asociadas al mismo disparador, se ejecutan secuencialmente en el orden mostrado en la lista de acciones. Si alguna acción devuelve { allow: false }, la ejecución se detiene y las acciones siguientes no se ejecutan.

Reordenar Acciones

En la página de lista de acciones, filtra por disparador. Arrastra el controlador de orden (el icono de seis puntos) en cualquier fila de acción para cambiar su posición. El nuevo orden se guarda automáticamente.

Editor Blueprint

Para usuarios que prefieren un enfoque visual para definir la lógica de las acciones, Auris ofrece el Editor Blueprint — un editor basado en nodos al estilo Unreal Engine para construir reglas de acciones sin escribir código.

Accede al Editor Blueprint en la página de detalle de cualquier acción haciendo clic en la pestaña Blueprint.

Tipos de Nodos

Usar el Editor Blueprint

1. El nodo Disparador se coloca automáticamente a la izquierda
2. Haz clic en Agregar Condición en la barra de herramientas para colocar un nodo de condición. Conéctalo al disparador o a una puerta lógica.
3. Haz clic en Agregar Puerta Lógica para combinar múltiples condiciones con lógica AND/OR
4. Conecta las salidas de condición a los nodos de acción (Denegar, Establecer Claims, etc.)
5. Haz clic en Auto-Layout para reorganizar los nodos automáticamente
6. Haz clic en Guardar — el blueprint se serializa a JavaScript y se guarda como código de la acción

El Editor Blueprint y el editor de código están sincronizados. Al cambiar entre ellos se muestra la representación en código del blueprint actual. El código escrito manualmente puede no ser siempre representable en el Editor Blueprint — las expresiones complejas se conservan como código pero no son editables visualmente.

Logs de Acciones

La pestaña Logs en la página de detalle de cualquier acción muestra el historial de ejecución de esa acción.

Haz clic en cualquier entrada del log para expandirla y ver:

• Datos de context completos pasados a la acción (con campos sensibles redactados)
• Valor de retorno de la acción
• Salida de consola (llamadas console.log desde el código de la acción)
• Stack trace del error (si ocurrió un error)

Filtrar Logs

Usa el selector de rango de fechas y el filtro de estado en la parte superior de la pestaña Logs para acotar la vista. Los logs se conservan por defecto durante 30 días.

Guías Relacionadas

• Flujo de Login Alojado — Cómo encajan las Acciones en el flujo de código de autorización OAuth 2.0
• Claims Personalizados — Configuración alternativa de claims sin código (para claims estáticos o basados en atributos)
• API de Acciones — Gestionar acciones de forma programática
• Integración con Webhooks — Webhooks salientes como alternativa para integraciones orientadas a eventos sin código en el path de autenticación