Conceptos clave

Esta página define los conceptos principales de Auris. Cada término se explica en el contexto de cómo lo usa Auris — no como una definición genérica del sector. Si eres nuevo en la gestión de identidad y accesos, leer esta página antes que las guías hará que el resto de la documentación sea más fácil de seguir.

Tenant

Un entorno aislado en Auris. Toda la configuración, usuarios, aplicaciones, roles y políticas pertenecen a un tenant. Los tenants no pueden compartir datos — una cuenta de usuario en el tenant A no puede autenticarse contra una aplicación registrada en el tenant B.

Internamente, cada tenant se corresponde con un realm de Keycloak. Keycloak aplica el aislamiento de realm a nivel del almacén de identidad.

En las solicitudes API, el tenant activo se identifica mediante la cabecera x-tenant. Los SDKs la establecen automáticamente en función del domain que configures en la inicialización.

Los despliegues de un solo tenant usan un único tenant (normalmente llamado 'default'). Los productos SaaS multitenancy crean un tenant por organización cliente — esto es diferente del concepto Organization propio de Auris, que es un agrupamiento B2B dentro de un único tenant de Auris.

Aplicación

Un cliente registrado en Auris. Todo software que use la autenticación de Auris debe registrarse como una aplicación. Una aplicación tiene:

• Un Client ID único (identificador público, seguro para incluir en código del navegador)

• Un Client Secret opcional (privado, solo para clientes M2M del lado del servidor)

• Una lista de URIs de redirección permitidas (aplicadas de forma exacta — sin comodines)

• Un Tipo de aplicación que determina qué flujos OAuth 2.0 están disponibles

Tipos de aplicación:

| Tipo | Descripción | Requiere Client Secret |

|------|-------------|----------------------|

| WEB | Aplicaciones basadas en navegador (SPA, SSR) | No — usa PKCE |

| MOBILE | Aplicaciones nativas iOS / Android | No — usa PKCE |

| API | Servidores de recursos que validan tokens | No |

| M2M | Servidor a servidor, trabajos en segundo plano | Sí |

Las aplicaciones pueden tener configurados Claims JWT personalizados — datos adicionales incrustados en los tokens de acceso emitidos para esa aplicación sin requerir una llamada API adicional.

Usuario

Una identidad gestionada por Auris dentro de un tenant. Los usuarios tienen:

• Un ID único (claim sub en los JWTs)

• Una dirección de email (identificador principal)

• Un nombre de usuario, nombre, apellido y número de teléfono opcionales

• Uno o más roles (mediante asignaciones de roles)

• Anulaciones de permisos opcionales (ALLOW o DENY en permisos específicos, independientemente de los roles)

• Uno o más métodos de autenticación (contraseña, cuentas sociales, passkeys, etc.)

• Configuraciones de 2FA opcionales (TOTP, SMS, WebAuthn)

Los usuarios se almacenan en Keycloak (para autenticación) y se replican en la base de datos Prisma de Auris (para metadatos RBAC, preferencias y datos de perfil extendidos).

Rol

Una colección de permisos con nombre. A los usuarios se les asignan roles; los roles definen lo que esos usuarios pueden hacer. Los roles tienen ámbito de tenant.

Un usuario puede tener múltiples roles. Al verificar un permiso, se evalúan todos los roles — si algún rol concede ALLOW y ninguno concede DENY, el permiso se otorga.

Los roles pueden ser jerárquicos (mediante valores de permiso INHERIT). Un rol base user podría otorgar acceso de lectura a la mayoría de recursos, mientras que un rol admin añade acceso de escritura por encima.

Los roles también pueden tener ámbito de aplicación — el mismo usuario puede tener roles diferentes (y por tanto permisos diferentes) en distintas aplicaciones registradas en Auris. Esto es útil cuando tu plataforma alberga múltiples productos con modelos de acceso diferentes.

Permiso

Una capacidad representada como una cadena acción:recurso. Ejemplos:

• manage:users — acceso CRUD completo a usuarios

• view:invoices — acceso de lectura a facturas

• approve:expenses — capacidad de aprobar informes de gastos

• create:tickets — capacidad de crear tickets de soporte

• export:payments — capacidad de exportar datos de pagos

Los permisos tienen valores de tres estados:

| Valor | Significado |

|-------|------------|

| ALLOW | Concede explícitamente este permiso |

| DENY | Revoca explícitamente este permiso, aunque otro rol lo conceda |

| INHERIT | Recurre al valor del rol padre (o al valor predeterminado del tenant si no hay padre) |

DENY siempre tiene prioridad sobre ALLOW. Si un usuario tiene el rol A que concede ALLOW en un permiso y el rol B que concede DENY en el mismo permiso, se deniega el acceso.

Las anulaciones de permisos de usuario pueden establecer el permiso de un usuario individual como ALLOW o DENY independientemente de sus roles. Se usa para casos excepcionales (p. ej., una concesión de permiso temporal durante un período de auditoría).

Token de acceso

Un JWT (JSON Web Token) de corta duración que prueba la identidad del usuario y lleva sus permisos. Los tokens de acceso:

• Están firmados con RS256 (RSA + SHA-256) usando la clave privada de Auris

• Pueden ser verificados por cualquier servicio con acceso al endpoint JWKS público de Auris

• Se envían en la cabecera HTTP Authorization: Bearer <token> a las APIs protegidas

• Son de corta duración (por defecto: 15 minutos — configurable por tenant)

El payload del token de acceso incluye:

 
{
 
  "sub": "uuid-de-usuario",
 
  "email": "[email protected]",
 
  "roles": ["admin", "billing_manager"],
 
  "aud": "tu-client-id",
 
  "iss": "https://auth.tudominio.com",
 
  "exp": 1700000000,
 
  "iat": 1699999100
 
}
 

Los claims personalizados configurados para una aplicación también se incluyen en el payload.

Token de refresco

Un token opaco de larga duración usado para obtener nuevos tokens de acceso una vez que el actual expira. Los tokens de refresco:

• Son opacos — son cadenas aleatorias, no JWTs. No llevan información por sí mismos.

• Son de larga duración (por defecto: 7 días — configurable por tenant)

• Son de un solo uso — cada vez que se usa un token de refresco para obtener un nuevo token de acceso, Auris invalida el token de refresco anterior y emite uno nuevo (rotación de tokens de refresco). Esto limita la ventana de exposición si se roba un token de refresco.

• Se almacenan de forma segura — los SDKs almacenan los tokens de refresco en cookies httpOnly (lado del servidor) o en almacenamiento cifrado (lado del cliente). Nunca los almacenes en localStorage.

El flujo de refresco del token de acceso es gestionado automáticamente por todos los SDKs de Auris. No necesitas implementarlo manualmente.

Token de identidad (ID Token)

Un token de OpenID Connect (OIDC) que contiene la información de perfil del usuario autenticado. Los tokens de identidad:

• Son JWTs, firmados con RS256 como los tokens de acceso

• Se emiten junto con el token de acceso durante el intercambio del código de autorización

• Están destinados a la aplicación cliente para mostrar información del usuario (nombre, email, avatar)

• No se envían a las APIs — las APIs deben usar el token de acceso, no el token de identidad

El payload del token de identidad sigue los claims estándar de OIDC:

 
{
 
  "sub": "uuid-de-usuario",
 
  "email": "[email protected]",
 
  "name": "Alice Smith",
 
  "given_name": "Alice",
 
  "family_name": "Smith",
 
  "picture": "https://...",
 
  "phone_number": "+34 123 456 789",
 
  "locale": "es",
 
  "iss": "https://auth.tudominio.com",
 
  "aud": "tu-client-id",
 
  "exp": 1700000000
 
}
 

PKCE

Proof Key for Code Exchange (RFC 7636). Una extensión de seguridad al flujo Authorization Code de OAuth 2.0 que previene ataques de interceptación de códigos de autorización.

Sin PKCE, si un atacante intercepta el código de autorización (p. ej., mediante una redirección maliciosa), podría intercambiarlo por tokens. PKCE lo previene al requerir que el cliente demuestre que inició el flujo.

Cómo funciona:

1. Antes de redirigir al inicio de sesión, el cliente genera un code_verifier aleatorio y calcula code_challenge = base64url(SHA256(code_verifier)).

2. El code_challenge se envía con la solicitud de autorización.

3. Tras la autenticación, Auris redirige de vuelta con el código de autorización.

4. Al intercambiar el código por tokens, el cliente envía el code_verifier original.

5. Auris recalcula el challenge y verifica que coincide — demostrando que el código fue obtenido por el mismo cliente que inició el flujo.

Auris aplica S256 (hash SHA-256) — no se acepta PKCE sin hash. Todos los SDKs de Auris gestionan la generación y verificación de PKCE automáticamente. Nunca necesitas implementarlo tú mismo.

RBAC

Control de Acceso Basado en Roles. El modelo de permisos donde:

• A los usuarios se les asignan roles

• Los roles tienen permisos

• Los permisos controlan el acceso a acciones y recursos

El RBAC responde la pregunta: “¿Qué puede hacer el rol de este usuario?” Es apropiado para la mayoría de escenarios de control de acceso — proteger rutas API, mostrar/ocultar elementos de UI y controlar operaciones de negocio.

En Auris, el RBAC se implementa como la Capa 2 del modelo de autorización en tres capas. La función requirePermission(req, 'action:resource') en las rutas API y el hook useRequirePermission('action:resource') en los componentes de UI son los puntos de aplicación principales.

FGA

Autorización Detallada. Un sistema de control de acceso basado en relaciones al estilo Zanzibar para permisos a nivel de objeto. El FGA responde la pregunta: “¿Puede este usuario específico acceder a este objeto específico?”

Donde el RBAC dice “los usuarios con el rol editor pueden editar documentos”, el FGA dice “la usuaria Alice puede editar el documento 42, el usuario Bob puede ver el documento 42, y el usuario Charlie no tiene acceso al documento 42”.

El FGA usa tres conceptos principales:

• Modelo de autorización — un esquema que define tipos de objeto y relaciones (p. ej., document tiene relaciones owner, editor, viewer)

• Tuplas de relación — hechos almacenados en la base de datos (p. ej., document:42#editor@user:alice)

• Verificación — una consulta recursiva que determina si un sujeto tiene una relación con un objeto siguiendo las reglas de reescritura del modelo

El FGA se implementa como la Capa 3 del modelo de autorización y reemplaza la integración con Ory Keto cuando está habilitado (FGA_ENGINE_ENABLED=true).

SSO

Single Sign-On. Un mecanismo que permite a los usuarios autenticarse una vez con un proveedor de identidad (IdP) y obtener acceso automáticamente a múltiples aplicaciones sin volver a introducir credenciales.

Auris soporta dos protocolos de SSO:

• SAML 2.0 — protocolo basado en XML ampliamente usado por IdPs empresariales (Okta, Azure AD, ADFS, PingIdentity). Auris actúa como Proveedor de Servicios (SP); el IdP del cliente es la fuente de identidad.

• OIDC (OpenID Connect) — protocolo moderno basado en JSON. Usado por Google Workspace, Microsoft Entra ID y otros.

Las conexiones SSO se configuran por Organización en Auris. Cuando el dominio de email de un usuario coincide con una conexión SSO configurada, Auris lo redirige automáticamente al IdP de su organización para la autenticación (detección de SSO basada en dominio).

SCIM

System for Cross-domain Identity Management (RFC 7643/7644). Un protocolo estándar para el aprovisionamiento y desaprovisionamiento automatizado de usuarios desde un proveedor de identidad hacia aplicaciones downstream.

Con SCIM habilitado:

• Cuando RRHH crea un nuevo empleado en Okta o Azure AD, ese usuario se aprovisiona automáticamente en Auris.

• Cuando un empleado es dado de baja, su cuenta Auris se desaprovisiona automáticamente.

• Las membresías de grupos pueden sincronizarse con roles de Auris.

Auris expone un endpoint de API SCIM 2.0 (/api/scim/v2/) que es compatible con los principales proveedores de identidad. Las conexiones SCIM se configuran por tenant en la Consola Auris en Configuración > Aprovisionamiento.

M2M

Machine-to-Machine. Autenticación servidor a servidor donde no interviene ningún usuario humano. Ejemplos incluyen trabajos en segundo plano, scripts cron, microservicios que se llaman entre sí y herramientas CLI.

La autenticación M2M usa el grant Client Credentials de OAuth 2.0:

1. El servidor envía su client_id y client_secret a POST /api/auth/token.

2. Auris valida las credenciales y emite un token de acceso con un claim type: 'm2m'.

3. El servidor usa este token para llamar a las APIs protegidas.

Los tokens M2M tienen ámbito — defines qué permisos (scopes) puede solicitar el cliente M2M. Esto limita el impacto si se compromete un client secret.

MFA

Autenticación Multifactor. Requerir a los usuarios que demuestren su identidad con más de un factor. Auris soporta tres métodos MFA:

| Método | Descripción |

|--------|------------|

| TOTP | Contraseña de un solo uso basada en tiempo mediante aplicaciones de autenticación (Google Authenticator, Authy, 1Password) |

| SMS OTP | Código de un solo uso enviado por SMS (con tecnología de Twilio) |

| WebAuthn | Llaves de seguridad de hardware y biometría del dispositivo (passkeys) mediante la API WebAuthn |

El MFA puede aplicarse globalmente (todos los usuarios), por rol o de forma adaptativa basándose en la puntuación de riesgo. El MFA adaptativo escala automáticamente a factores adicionales cuando se detectan señales de riesgo (dispositivo nuevo, país nuevo, viaje imposible, uso de VPN) — sin requerir que todos los usuarios usen MFA en cada inicio de sesión.

Actions

Funciones JavaScript personalizadas que se ejecutan durante los flujos de autenticación en un entorno sandbox. Las Actions permiten extender el comportamiento de Auris sin necesidad de modificar la plataforma.

Casos de uso:

• Denegar el inicio de sesión a usuarios que no han aceptado los últimos términos de servicio

• Añadir un claim personalizado al token de acceso basado en una consulta a la base de datos

• Enviar una notificación de Slack cuando un usuario específico inicia sesión

• Aplicar comprobaciones en el momento del inicio de sesión (estado de la cuenta, estado de la suscripción, cumplimiento del dispositivo)

Las Actions se ejecutan de forma síncrona en el flujo de autenticación. Si una Action lanza un error o deniega explícitamente la solicitud, la autenticación se bloquea. Las Actions tienen un tiempo de espera configurable (por defecto: 5 segundos).

Para la edición visual de lógica de Actions compleja, el Editor de Blueprints proporciona una interfaz de arrastrar y soltar basada en nodos (similar a los Blueprints de Unreal Engine) que genera el código de la action subyacente.

Organización

Una entidad B2B dentro de un tenant. Las organizaciones se usan cuando construyes un producto que vendes a otras empresas — cada uno de tus clientes se modela como una Organización.

Cada organización tiene:

• Un listado de miembros con roles (OWNER, ADMIN, MEMBER, VIEWER)

• Una conexión SSO empresarial opcional (SAML u OIDC) con ámbito en esa organización

• Flujos de invitación — envía invitaciones por email a nuevos miembros (basadas en tokens, expiración de 7 días)

• Detección de SSO basada en dominio — cuando el dominio de email de un usuario coincide con la conexión SSO de la organización, Auris lo redirige automáticamente a su IdP

Las organizaciones son diferentes de los tenants. Un tenant es el límite de aislamiento de nivel superior; una organización es un agrupamiento de usuarios dentro de un único tenant.

Dominio personalizado

Una función que te permite servir las páginas de inicio de sesión alojadas por Auris desde tu propio dominio (p. ej., auth.tuempresa.com) en lugar de la URL predeterminada de Auris. Esto proporciona una experiencia de autenticación de marca blanca.

Los dominios personalizados requieren verificación DNS (registro CNAME o TXT). Auris gestiona el aprovisionamiento del certificado SSL automáticamente una vez que se verifica el registro DNS.

Webhook

Un callback HTTP que Auris envía a tu servidor cuando ocurren eventos específicos. Los webhooks están firmados con HMAC-SHA256 usando un secreto con el prefijo whsec_, lo que te permite verificar que la solicitud se originó en Auris.

Se soportan más de 180 tipos de eventos, agrupados en 18 categorías (autenticación, usuarios, organizaciones, facturas, tickets, chat, CRM y más). Los fallos de entrega se reintentAN con retroceso exponencial.

Blueprint

Un editor visual de nodos para construir lógica de Actions sin escribir JavaScript directamente. El Editor de Blueprints usa una interfaz de arrastrar y soltar con nodos tipados:

• Nodo de disparador — el evento de autenticación que inicia el flujo

• Nodos de condición — lógica if/then (comparaciones de campos, operadores)

• Nodos de compuerta lógica — combinadores AND/OR

• Nodos de acción — operaciones a realizar (denegar, establecer claims, establecer metadatos, registrar)

El Blueprint se serializa en una estructura de reglas JSON que el motor de Actions evalúa en tiempo de ejecución. Puedes alternar entre la vista Blueprint y la vista de código sin procesar en la misma action.

Descubrimiento OIDC

El mecanismo estándar para que los clientes OIDC descubran la configuración de un proveedor de identidad. Auris publica su documento de descubrimiento OIDC en:

GET /.well-known/openid-configuration

Este documento enumera el endpoint de autorización, el endpoint de tokens, el URI de JWKS, los tipos de respuesta soportados, los scopes y los algoritmos de firma. Las bibliotecas estándar de OAuth 2.0 y OIDC pueden autoconfiguarse desde esta URL — solo necesitas proporcionar el dominio de Auris.