Arquitectura

Esta página describe cómo está estructurado Auris internamente y cómo interactúan sus componentes. Comprender la arquitectura es útil al depurar problemas de integración, planificar los límites de seguridad o evaluar Auris para un despliegue empresarial.

Visión general

Auris es una plataforma en capas. Tu aplicación se comunica con la API y los SDKs de Auris. La capa API proporciona el emisor de tokens nativo y los planos de auth, y añade autorización, seguridad y servicios para desarrolladores.

Auth planes (native Auris issuer + residual seams): token issuer (Auris-minted opaque tenant_id JWTs), session/logout (Auris authoritative; IdP end_session from DB; no /broker/ logout), IdP federation (native SP + TenantIdentityProvider / SsoConnection SoT; KC Admin sync/read gone), credential-store posture (IdP secrets in Auris DB). Hard isolation = opaque Tenant.id. Routing slug in iss /realms/<slug> is not an authz key. Not Keycloak-zero.

Modelo de tenant

Cada despliegue de Auris soporta múltiples tenants. Un tenant es un entorno completamente aislado con sus propios:

• Cuentas de usuario y credenciales
• Aplicaciones (clientes OAuth 2.0 registrados)
• Roles, permisos y políticas de autorización
• Configuración de seguridad (límites de velocidad, política MFA, reglas de IP, CAPTCHA)
• Plantillas de correo, identidad de marca y dominios personalizados
• Registros de auditoría y endpoints de webhook

Internamente, cada tenant se corresponde directamente con un tenant Auris (Tenant.id opaco). Esto significa que el aislamiento de tenants se aplica a nivel del almacén de identidad — los usuarios del tenant A no pueden autenticarse contra las aplicaciones del tenant B, y sus datos nunca se mezclan.

La cabecera x-tenant se usa en la mayoría de las llamadas a la API de Auris para identificar el contexto del tenant activo. Los SDKs gestionan esto automáticamente en función del domain (o identificador de tenant) que configures en la inicialización.

Autorización en tres capas

Auris implementa la autorización en tres capas, cada una añadiendo más granularidad que la anterior:

Capa 1 — Autenticación Auris (emisor JWT)

Los access tokens los emite y verifica Auris (issuer nativo). La firma es HS256 (JWT_SECRET) por defecto, o RS256 cuando está configurado. tenant_id opaco siempre está presente en tokens con ámbito de tenant. Los tokens crudos de IdP externos no se aceptan para authz de API (introspección Keycloak fail-closed).

Los claims incluyen iss (issuer Auris + /realms/<slug> para routing), sub, email, tenant_id, roles. No asumas realm_access.roles.

Capa 2 — RBAC con Prisma (Roles de grano fino con permisos de tres estados)

Auris mantiene su propio almacén de roles y permisos en PostgreSQL (mediante Prisma). Esta capa proporciona:

• Roles con un conjunto de permisos con nombre
• Permisos en formato acción:recurso (p. ej., manage:users, view:invoices, approve:expenses)
• Valores de permiso de tres estados: ALLOW, DENY o INHERIT
  • ALLOW — concede explícitamente el permiso
  • DENY — lo revoca explícitamente, aunque otro rol lo conceda (DENY tiene prioridad)
  • INHERIT — recurre al rol padre o al valor predeterminado del tenant
• Anulaciones de permisos por usuario que pueden conceder o revocar permisos específicos independientemente del rol
• Permisos con ámbito de aplicación — el mismo usuario puede tener permisos diferentes en distintas aplicaciones registradas

Las comprobaciones de permisos ocurren en el servidor mediante POST /api/roles/check. El panel aplica los permisos en cada ruta API usando requirePermission(req, 'action:resource').

Capa 3 — FGA (Autorización Detallada / ReBAC al estilo Zanzibar)

La capa FGA implementa control de acceso basado en relaciones a nivel de objeto, inspirado en el artículo de Google Zanzibar. Responde preguntas como “¿puede la usuaria Alice leer el documento 42?” o “¿es el usuario Bob miembro de la organización X?”.

El modelo FGA consta de:

• Modelo de autorización — un esquema (escrito en DSL de OpenFGA) que define los tipos de objeto y las relaciones entre ellos
• Tuplas de relación — hechos almacenados en la base de datos (p. ej., document:42#viewer@user:alice)
• Motor de verificación — un algoritmo Zanzibar recursivo que evalúa si un sujeto tiene una relación con un objeto, siguiendo reescrituras de conjuntos de usuarios computados y de tupla a conjunto de usuarios hasta una profundidad configurable (por defecto: 25)

FGA soporta seis tipos de reglas de reescritura: this, computedUserset, tupleToUserset, union, intersection y exclusion. También soporta expand (listar todos los sujetos para una relación) y listObjects (listar todos los objetos a los que un sujeto tiene acceso mediante búsqueda inversa).

Cuando FGA_ENGINE_ENABLED=true, las comprobaciones de acceso a recursos se enrutan al motor FGA. La integración legada con Ory Keto permanece como alternativa y está obsoleta.

Tipos de aplicación

Auris soporta cuatro tipos de aplicación, correspondientes a los perfiles de cliente OAuth 2.0 estándar:

Cada aplicación recibe un Client ID (público) y opcionalmente un Client Secret (para clientes confidenciales). Las URIs de redirección se registran por aplicación y se aplican de forma exacta — no se permiten comodines.

Para las aplicaciones M2M, los scopes controlan qué permite el token (p. ej., read:users, write:invoices). Se pueden adjuntar claims JWT personalizados por aplicación para incluir datos adicionales en los tokens de acceso sin una llamada extra a la API.

Flujo de tokens

Auris emite tres tipos de tokens siguiendo la especificación OpenID Connect:

Token de acceso

• Formato: JWT, default de código JWT_ALGORITHM=HS256 (RS256 solo si está configurado)
• Duración: JWT_EXPIRATION default 3600 s
• Contiene (mint Auris): iss, sub, email, tenant_id (opaco), realm / tenant_slug, roles, opcionales org_id, tenants
• Uso: Authorization: Bearer <token>
• Verificación: solo HS256/RS256 local (verifyJWT). Sin introspección Keycloak. JWKS solo en el path RS256

Token de refresco

• Formato: JWT con type: 'refresh' (no una cadena opaca)
• Duración: 30 días en createTokens
• Uso: POST /api/auth/token grant refresh_token
• Seguridad: rotación de un solo uso con detección de reutilización

Token de identidad (ID Token)

• Formato: JWT, firmado con RS256
• Contiene: Claims de identidad del usuario (name, email, picture, phone_number, locale, atributos personalizados)
• Uso: Usado por la aplicación cliente para mostrar información del usuario — no se envía a las APIs
• Verificado: Mismo endpoint JWKS que el token de acceso

Descubrimiento OIDC

Auris publica un documento estándar de descubrimiento OIDC en:

GET /.well-known/openid-configuration

Este endpoint devuelve el endpoint de autorización, el endpoint de tokens, el URI de JWKS, los tipos de grant soportados, los scopes y los algoritmos de firma. Los clientes OIDC estándar pueden autoconfigurase desde este documento.

El endpoint JWKS:

GET /.well-known/jwks.json

Devuelve el conjunto de claves públicas actuales en formato JWK. Las claves usan RS256. La rotación de claves está soportada — las claves antiguas permanecen en la respuesta JWKS durante un período de gracia tras la rotación para que los tokens en vuelo sigan siendo válidos.

Páginas de inicio de sesión alojadas

Auris proporciona páginas de inicio de sesión alojadas servidas desde el dominio Auris (o tu dominio personalizado). Estas páginas gestionan de extremo a extremo el flujo OAuth 2.0 Authorization Code + PKCE:

1. Tu aplicación llama a loginWithRedirect() (SDK) o redirige a GET /api/oauth/authorize
2. El usuario ve la página de inicio de sesión alojada por Auris, con el estilo de la identidad de marca de tu tenant (logo, colores, favicon)
3. Tras una autenticación exitosa, Auris redirige de vuelta a tu redirect_uri con un código de autorización
4. Tu aplicación intercambia el código por tokens en POST /api/auth/token (gestionado automáticamente por los SDKs)
5. El SDK almacena el token de acceso y el token de refresco, y el usuario queda autenticado

Todas las capas de seguridad (CAPTCHA, limitación de velocidad, protección contra fuerza bruta, detección de inicios de sesión sospechosos, MFA adaptativo) se aplican durante el flujo de inicio de sesión alojado. No necesitas implementarlas en tus propias páginas de inicio de sesión.

Motor de Actions

Las Actions son funciones JavaScript personalizadas que se ejecutan durante los flujos de autenticación. Se ejecutan en un entorno sandbox con un ámbito restringido — require, import, process, eval, fs y child_process están bloqueados.

Las Actions se pueden activar en seis puntos:

Las Actions tienen acceso a un objeto de contexto que contiene el usuario, el tenant, la aplicación y los datos del evento. Pueden denegar el flujo de autenticación, enriquecer el token con claims adicionales o llamar a servicios externos.

Arquitectura de seguridad

La seguridad se aplica en capas, desde la red hasta la aplicación:

Limitación de velocidad

Cuatro niveles de limitación de velocidad con contadores de ventana deslizante:

El estado de la limitación de velocidad usa contadores en memoria. Se devuelven las cabeceras estándar Retry-After y X-RateLimit-* en las respuestas 429.

Protección contra fuerza bruta

Los intentos de inicio de sesión fallidos se rastrean por cuenta. Tras un umbral configurable (por defecto: 5 fallos en 15 minutos), la cuenta queda bloqueada temporalmente. Los administradores pueden ver y desbloquear cuentas desde la consola.

CAPTCHA

Se soportan tres proveedores: Cloudflare Turnstile, hCaptcha y Google reCAPTCHA v3. El CAPTCHA se puede configurar para activarse siempre, solo en solicitudes sospechosas o tras un número de intentos de inicio de sesión fallidos. La verificación del CAPTCHA se aplica en el servidor — los tokens del lado del cliente se validan contra la API del proveedor antes de que proceda la autenticación.

Reglas de IP

Cada tenant puede definir reglas de permitir y bloquear basadas en CIDR. Las reglas pueden tener ámbito en todo el tenant o en una aplicación específica. Las reglas de bloqueo se evalúan primero; si la IP de una solicitud coincide con una regla de bloqueo, se rechaza antes de que se ejecute ninguna lógica de autenticación.

Detección de inicios de sesión sospechosos

Después de cada autenticación exitosa, Auris evalúa cinco señales de riesgo:

• Dispositivo nuevo — la huella digital del dispositivo no se ha visto antes para este usuario
• IP nueva — la dirección IP no se ha usado antes para este usuario
• País nuevo — el país geográfico difiere de las sesiones anteriores
• Viaje imposible — la distancia entre este inicio de sesión y el anterior es demasiado grande para el tiempo transcurrido
• IP de VPN / proxy / datacenter — la IP se identifica como un nodo de salida VPN, proxy abierto o dirección de datacenter

Si se activa alguna señal, se registra un SuspiciousLoginEvent y se envía una notificación de alerta. Según la configuración del tenant, los inicios de sesión sospechosos pueden bloquearse, desafiarse con MFA de paso adicional o permitirse solo con registro.

Vinculación de tokens DPoP

Para aplicaciones que requieren el máximo nivel de seguridad de tokens, Auris soporta Demostración de Prueba de Posesión (DPoP, RFC 9449). DPoP vincula los tokens de acceso a la clave pública de un cliente, evitando que los tokens robados sean usados por un cliente diferente. El middleware dpop-validator valida las pruebas DPoP en cada solicitud para las aplicaciones con DPoP habilitado.

Resumen del modelo de datos

Las entidades principales en Auris y sus relaciones: