> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Servicio Auth
> Emite tokens OAuth2/OIDC, valida sesiones, verifica permisos y gestiona los desafíos de MFA con el servicio Auth.
Auth es el servicio de acceso en tiempo de ejecución de Access Manager. Se sitúa entre tus productos Lerian protegidos y el proveedor de identidad configurado, y ofrece a los productos una única interfaz para el ciclo de vida del token, la información de usuario, las comprobaciones de permisos, el cierre de sesión y la verificación de inicio de sesión con MFA.
Usa Auth cuando necesites:
* solicitar tokens de acceso para usuarios humanos o aplicaciones máquina a máquina;
* refrescar un token de acceso expirado;
* recuperar información de usuario compatible con OIDC;
* validar si un sujeto puede realizar una acción sobre un recurso;
* recuperar los permisos disponibles para el usuario autenticado;
* finalizar una sesión de usuario;
* iniciar y verificar desafíos de MFA durante el inicio de sesión.
Auth delega los datos de identidad en el proveedor de identidad y cachea con Valkey los datos de token, permisos y MFA para reducir las llamadas repetidas durante la operación normal.
## Flujos principales
***
Auth admite los flujos de acceso que usan los productos e integraciones de Lerian.
### Flujo de autenticación
1. **Solicitud de token**
* Los usuarios humanos se autentican con el grant `password`.
* Las integraciones de servicio se autentican con el grant `client_credentials`.
* Auth reenvía la solicitud al proveedor de identidad y devuelve el token de acceso, el token de refresco y el token ID cuando corresponde.
2. **Refresco de token**
* Los clientes intercambian un token de refresco por un nuevo token de acceso.
* Auth valida el token de refresco con el proveedor de identidad antes de emitir el nuevo token.
3. **Validación de token**
* Los productos protegidos validan los bearer tokens antes de aceptar una solicitud.
* Auth extrae las claims de token de confianza para identificar el sujeto y el contexto de tenant.
* Los resultados de validación pueden cachearse para reducir las llamadas repetidas al proveedor de identidad.
**Contexto de tenant** — En despliegues SaaS y BYOC multi-tenant, el JWT emitido contiene un claim `tenantId`. Este claim es resuelto automáticamente por la plataforma en cada solicitud de API — no necesitas enviar un identificador de tenant en headers ni en el cuerpo de la solicitud. Tu token establece tu alcance. Aprende más sobre [multi-tenancy](/es/multi-tenancy).
### Manejo de tokens multi-tenant
Cuando el modo multi-tenant está activado, Auth mantiene las operaciones de token y permisos dentro del tenant resuelto para el sujeto autenticado.
Para usuarios humanos, el grant `password` resuelve el tenant del usuario antes de solicitar tokens al proveedor de identidad configurado. Los flujos de refresh-token usan el contexto de tenant que porta el token existente, de modo que un refresco no puede mover la sesión a otro tenant.
Para integraciones máquina a máquina, Auth resuelve las credenciales de aplicación y el conjunto de permisos a partir de la organización de la aplicación. El token resultante queda acotado al tenant de esa aplicación.
En despliegues single-tenant, Auth usa la organización predeterminada configurada y no requiere un claim de tenant.
### Recorrido de la resolución de tenant
Cuando multi-tenancy está habilitado, una sola solicitud recorre siete pasos desde la llamada del cliente hasta la respuesta aislada. Cada paso reduce el alcance al tenant que llama y se niega a continuar si no se puede establecer el contexto de tenant.
Un cliente llama a una API de producto protegida con un bearer token. El cliente nunca envía un identificador de tenant en headers ni en el cuerpo — el token es la única fuente del contexto de tenant.
El producto valida el bearer token antes de aceptar la solicitud. Auth verifica el token con el proveedor de identidad (o con un resultado de validación cacheado) y rechaza cualquier token expirado, malformado o sin firma.
Auth extrae los claims confiables del token validado, incluido el claim `tenantId` que identifica el tenant del llamador. Este claim se establece en la emisión y no puede ser sobrescrito por la solicitud.
El middleware multi-tenant del producto lee el `tenantId` de los claims validados y establece el contexto de tenant para el ciclo de vida de la solicitud.
El middleware resuelve el tenant a su configuración de servicio a través de la capa de plataforma (usando el caché local cuando es válido), obteniendo los detalles de conexión de la infraestructura aislada de ese tenant.
El producto abre — o reutiliza del pool por tenant — una conexión escopada exactamente a la base de datos o esquema de ese tenant. Ningún dato de otro tenant es alcanzable a través de esta conexión.
La operación se ejecuta contra los datos aislados y la respuesta se devuelve al llamador, escopada por completo al tenant resuelto.
#### Contexto de tenant fail-closed
La resolución de tenant es **fail-closed**: si no se puede establecer el contexto de tenant, la solicitud se rechaza en lugar de atenderse contra un alcance predeterminado o compartido. Una solicitud se deniega cuando el token es inválido o le falta el claim `tenantId`, cuando el tenant no puede resolverse a una configuración de servicio, o cuando el servicio de multi-tenancy es inalcanzable y no existe una configuración cacheada válida (consulta el [circuit breaker](/es/multi-tenancy#circuit-breaker)). La plataforma nunca recurre a los datos de otro tenant ni a una conexión sin alcance cuando la resolución falla.
El comportamiento fail-closed significa que un fallo en la resolución de tenant se manifiesta como una solicitud denegada, no como un acceso ampliado silenciosamente. Esto es intencional — garantiza que ninguna operación se ejecute sin un alcance de tenant confirmado.
### Flujo de inicio de sesión con MFA
1. **Desafío requerido**
* Cuando se requiere MFA, Auth devuelve un estado de desafío de MFA en lugar de completar el inicio de sesión de inmediato.
* El usuario recibe un código de desafío a través del método configurado.
2. **Verificación del desafío**
* El usuario envía el token de MFA y el código de acceso.
* Auth verifica el desafío y devuelve los tokens de acceso cuando la verificación es correcta.
3. **Controles de sesión**
* Los desafíos de MFA expiran tras el TTL configurado.
* Los intentos fallidos están limitados para proteger la cuenta de adivinación repetida.
### Flujo de autorización
1. **Aplicar acceso**
* Un producto protegido pregunta si el sujeto autenticado puede realizar una acción específica sobre un recurso específico.
* Auth evalúa la solicitud contra los permisos de Access Manager configurados.
* Las decisiones de autorización correctas pueden cachearse para mejorar el rendimiento.
2. **Recuperar permisos**
* Un cliente puede recuperar los permisos disponibles para el usuario autenticado.
* Auth devuelve los permisos como un mapa de recursos a acciones permitidas.
### Flujo de información del usuario
1. **Solicitud de perfil**
* El cliente solicita información del perfil de usuario con un bearer token.
* Auth valida el token y recupera los detalles del usuario del proveedor de identidad.
* Auth devuelve la información de usuario compatible con OIDC.
### Flujo de cierre de sesión
1. **Cierre de sesión del usuario**
* El cliente envía una solicitud de cierre de sesión con la pista de token ID (ID token hint).
* Auth invalida la sesión en el proveedor de identidad.
* Las entradas de caché relacionadas se eliminan.
## Descripción general de la API
***
Auth expone APIs para:
* solicitar tokens de acceso con `password` o `client_credentials`;
* refrescar tokens de acceso;
* finalizar sesiones de usuario;
* validar permisos de usuario;
* recuperar información de usuario;
* recuperar permisos de usuario;
* iniciar un desafío de MFA;
* verificar un desafío de inicio de sesión con MFA.
El acceso a las APIs de Auth está protegido por estrictos controles de permiso. Para obtener detalles técnicos sobre endpoints y uso, consulta la documentación de [APIs de Auth](/es/reference/access-manager/am-auth-apis).
## Decisiones de permisos
***
Cuando un producto protegido pregunta a Auth si un sujeto puede realizar una acción sobre un recurso, Auth resuelve el sujeto (un usuario humano o una aplicación máquina a máquina), busca los permisos asociados a él y devuelve una decisión de autorizado o denegado.
Para usuarios humanos, los permisos provienen de los grupos asignados en Identity. Para aplicaciones máquina a máquina, los permisos provienen del conjunto de permisos configurado de la aplicación. Auth no inventa permisos; evalúa los datos que gestiona Identity.
Para el modelo completo de sujeto/recurso/acción, ejemplos y cómo se protegen las rutas, consulta [Aplicación a nivel de producto](/es/platform/access-manager/product-level-enforcement). Para inspeccionar a qué puede llegar el sujeto autenticado, usa [Obtener permisos del usuario](/es/reference/access-manager/retrieve-user-permissions).
## Almacenamiento de datos y caching
***
Auth usa datos de política estructurados y entradas de caché para reducir el trabajo repetido:
* **Datos de política**: almacena las reglas de control de acceso para usuarios, grupos y aplicaciones.
* **Caché de token**: almacena los resultados de validación de token.
* **Caché de permisos**: almacena las decisiones de autorización correctas.
* **Caché de permisos de usuario**: almacena el mapa de recursos y acciones disponibles para un usuario.
* **Caché de MFA**: almacena el estado temporal del desafío, los contadores de intentos y el estado de recordar dispositivo cuando está configurado.
## Pruebas y fiabilidad
***
**Auth** se somete a pruebas continuas para mantener la fiabilidad y la seguridad. Las pruebas cubren:
* **Flujos de autenticación y validación de tokens**.
* **Aplicación del control de acceso**.
* **Rendimiento y eficiencia del caching**.
Auth también ejecuta evaluaciones de seguridad y monitorización continuas en todos estos flujos.