Tokens de sesión
Passwork utiliza un modelo de autenticación basado en tokens con un par Access Token / Refresh Token.
Descripción general del sistema de tokens
| Token | Propósito | Duración |
|---|---|---|
| Access Token | Autenticación de solicitudes a la API | ~2,8 horas |
| Refresh Token | Renovación del Access Token | 36 horas |
¿Por qué no JWT?
Los tokens de Passwork son cadenas aleatorias, no JWT. Para un gestor de contraseñas, este enfoque proporciona mayor seguridad:
| Característica | Tokens de Passwork | JWT |
|---|---|---|
| Formato | Cadena Base64 aleatoria | JSON con firma |
| Información en el token | Ninguna | Payload con datos |
| Validación | Consulta a la base de datos | Verificación de firma |
| Revocación del token | Instantánea (eliminación de la BD) | Requiere lista negra |
Ventajas de seguridad:
-
Revocación instantánea de la sesión. Si se sospecha un compromiso, el administrador o el usuario pueden terminar inmediatamente cualquier sesión — el token se elimina de la base de datos y queda inválido al instante. JWT sigue funcionando hasta su expiración.
-
Control total de sesiones. Todas las sesiones activas se almacenan en el servidor, lo que permite rastrear dispositivos, direcciones IP y el momento de la última actividad. El administrador ve el panorama completo y puede gestionar el acceso.
-
Sin datos sensibles en el token. JWT contiene un payload con información del usuario que puede leerse (Base64 no es cifrado). Los tokens de Passwork son simplemente identificadores aleatorios sin ninguna información.
-
Resistencia al compromiso de claves. Si se filtra la clave secreta de JWT, un atacante puede crear tokens válidos para cualquier usuario. Con tokens de sesión, este vector de ataque no existe.
-
Sin clave secreta de firma. JWT requiere almacenar una clave privada en el servidor para firmar tokens — otro secreto que proteger, rotar y controlar. Los tokens de sesión de Passwork son simplemente cadenas aleatorias, no se necesitan claves secretas para su generación.
Access Token
Características
| Parámetro | Valor |
|---|---|
| Longitud | 256 bits |
| Formato | Base64 |
| Longitud de cadena | ~44 caracteres |
| Entropía | 256 bits |
| Duración predeterminada | 10.000 segundos (~2,8 horas) |
Generación
El Access Token se genera con un generador de números aleatorios criptográficamente seguro:
token = base64(random_bytes(32))
Validación
En cada solicitud, el servidor:
- Extrae el token (de la cookie o del encabezado, según el modo)
- Busca el token en la base de datos
- Verifica la duración
- Vincula la solicitud al usuario
Modos de transmisión de tokens
Passwork utiliza dos modos de transmisión del Access Token según el tipo de cliente:
Modo navegador (aplicación web)
Para la aplicación web, el Access Token se transmite mediante Cookie HttpOnly:
| Parámetro | Valor |
|---|---|
| HttpOnly | Sí — inaccesible para JavaScript (protección XSS) |
| Secure | Sí — solo HTTPS |
| SameSite | Strict — protección CSRF |
En este modo, el navegador adjunta automáticamente la cookie a cada solicitud. El Access Token no se devuelve en el cuerpo de la respuesta durante la autenticación — solo en el encabezado Set-Cookie.
Modo API (escritorio, extensión, móvil)
Para clientes API, el Access Token se transmite en el encabezado Authorization:
Authorization: Bearer {access_token}
En este modo, el Access Token se devuelve en el cuerpo de la respuesta durante la autenticación, y el cliente gestiona el almacenamiento de forma independiente.
Comparación de modos
| Parámetro | Modo navegador | Modo API |
|---|---|---|
| Clientes | Aplicación web | Escritorio, Extensión, Móvil |
| Transmisión del token | Cookie HttpOnly | Encabezado Authorization |
| Protección XSS | ✓ (HttpOnly) | Depende del cliente |
| Gestión del token | Navegador (automática) | Cliente (manual) |
Refresh Token
Características
| Parámetro | Valor |
|---|---|
| Longitud | 256 bits |
| Formato | Base64 |
| Longitud de cadena | ~44 caracteres |
| Entropía | 256 bits |
| Duración predeterminada | 129.600 segundos (36 horas) |
Propósito
El Refresh Token se utiliza para obtener un nuevo Access Token sin necesidad de reautenticación. Más información sobre el proceso de renovación en la sección Rotación de tokens.
Configuración de duración
Por roles de usuario
La duración de los tokens se configura a nivel de rol de usuario:
| Configuración | Valor predeterminado |
|---|---|
| Duración del Access Token | 10.000 seg (~2,8 horas) |
| Duración del Refresh Token | 129.600 seg (36 horas) |
Ejemplos de configuración
| Escenario | TTL Access | TTL Refresh |
|---|---|---|
| Usuario estándar | 10.000 seg | 129.600 seg |
| Alta seguridad | 1.800 seg (30 min) | 14.400 seg (4 horas) |
| Comodidad | 28.800 seg (8 horas) | 604.800 seg (7 días) |
Ciclo de vida de la sesión
Ciclo de vida completo
T=0: Autenticación. El usuario introduce las credenciales. El servidor crea el Access Token (TTL: 2,8 horas) y el Refresh Token (TTL: 36 horas).
T=2,8h: Access Token expirado. El cliente envía el Refresh Token. El servidor emite nuevos tokens. El Refresh Token anterior queda invalidado.
T=36h: Refresh Token expirado. Se requiere reautenticación. El usuario introduce las credenciales de nuevo.
Escenario alternativo — Cierre de sesión. El usuario hace clic en «Cerrar sesión». Ambos tokens quedan invalidados. La sesión se termina.
Invalidación de tokens
Todos los tokens de sesión se invalidan en los siguientes casos:
- Cierre de sesión del usuario
- Cambio de contraseña maestra
- Restablecimiento de la contraseña maestra por el administrador
Rotación de tokens
Modo estándar (aplicaciones)
Para la aplicación web, la extensión del navegador, y las aplicaciones móviles y de escritorio, se aplica una política estricta de rotación de tokens.
Al actualizar la sesión, el cliente envía el Access Token y el Refresh Token simultáneamente, y recibe un nuevo par de tokens en respuesta. Esto proporciona una rotación continua de ambos tokens, previniendo la reutilización de tokens robados.
Modo de automatización (API)
Para tareas de DevOps y automatización, la rotación estricta suele ser inconveniente. Por ello, para las sesiones creadas mediante la generación de tokens API, está disponible un modo alternativo:
- Actualización solo del Access Token sin cambio del Refresh Token
- Renovación separada del Refresh Token cuando sea necesario
Esto permite utilizar Refresh Tokens de larga duración en scripts y pipelines de CI/CD.
Seguridad de los tokens
Protección contra interceptación
| Amenaza | Protección |
|---|---|
| Interceptación de red | Se requiere HTTPS/TLS |
| Ataque XSS | Cookies HttpOnly (Modo navegador) |
| CSRF | CSRF Token + cookies SameSite |
CSRF Token
Propósito
El CSRF Token protege contra ataques de falsificación de solicitudes entre sitios. Se requiere para todas las operaciones de modificación.
Características
| Parámetro | Valor |
|---|---|
| Tamaño | 256 bits |
| Formato | Hexadecimal (64 caracteres) |
| Entropía | 256 bits |
| Generador | Criptográficamente seguro |
Uso
El CSRF Token se transmite en el encabezado de cada solicitud:
X-CSRF-Token: {csrf_token}
Requisitos por tipo de cliente
| Tipo de cliente | CSRF Token |
|---|---|
| Aplicación web (Modo navegador) | ✓ Requerido (generado y validado automáticamente) |
| Extensión del navegador | Opcional (a petición del cliente) |
| Aplicación móvil | Opcional (a petición del cliente) |
| API | — (no se utiliza) |
Cookie Sign
Propósito
Función opcional de protección adicional para el Modo navegador. Vincula la sesión al contexto del cliente, protegiendo contra el robo de cookies y el secuestro de sesión.
Cómo funciona
Cuando está habilitado, el servidor calcula una firma basada en:
- Dirección IP del cliente
- User-Agent del navegador
- Identificador de sesión
- Clave secreta (60 caracteres, ~357 bits de entropía)
La firma se calcula mediante la fórmula:
cookieSign = HMAC-SHA512(IP + UserAgent + SessionID, secret)
La firma se guarda en una cookie HttpOnly separada y se verifica en cada solicitud.
Protección contra ataques
| Ataque | Protección |
|---|---|
| Secuestro de sesión | La cookie robada no funciona desde una IP diferente |
| Robo de cookies | La cookie es inútil sin la coincidencia de IP + User-Agent |
Limitaciones
- El cambio de IP (VPN, red móvil) requiere reautenticación
- La actualización del navegador puede cambiar el User-Agent
Activación
La función la habilita el administrador en la configuración del sistema. Deshabilitada de forma predeterminada por compatibilidad con usuarios con IP dinámica.
Tipos de cliente
Passwork distingue cuatro tipos de cliente con diferentes mecanismos de seguridad:
| Funcionalidad | Web | Extensión del navegador | Móvil | API |
|---|---|---|---|---|
| Modo de transmisión de token | Modo navegador | Modo API | Modo API | Modo API |
| Access Token | Cookie | Encabezado | Encabezado | Encabezado |
| CSRF Token | ✓ Requerido | Opcional | Opcional | — |
| Cookie Sign | Opcional | — | — | — |
| Código PIN | — | ✓ Compatible | — | — |
Extensión del navegador — el único tipo de cliente que admite código PIN del lado del servidor. El PIN se verifica en el servidor, lo que abre una ventana temporal para el uso de la API. Después del tiempo de espera, la sesión se bloquea hasta que se vuelva a introducir el PIN. Con múltiples intentos incorrectos, el servidor termina inmediatamente la sesión. Esto protege contra el robo de tokens — incluso con el compromiso del token, un atacante no puede usar la API sin conocer el PIN.
Encabezados HTTP
Encabezados de autenticación
| Encabezado | Descripción | Modo |
|---|---|---|
Authorization | Access Token (Bearer {token}) | Modo API |
Cookie | Access Token (automático) | Modo navegador |
X-CSRF-Token | Protección CSRF | Todos los modos |
X-Master-Key-Hash | Hash de la clave maestra | Cuando sea necesario |
Almacenamiento de tokens en el cliente
Cada tipo de cliente implementa un almacenamiento seguro de tokens según las capacidades de la plataforma:
- Aplicación web — el Access Token se almacena en Cookie HttpOnly, inaccesible para JavaScript (protección XSS)
- Aplicaciones de escritorio y móviles — los tokens se almacenan en el almacenamiento seguro del SO con acceso restringido
- Extensión del navegador — se utiliza almacenamiento aislado del navegador, inaccesible desde páginas web
Múltiples sesiones
Sesiones paralelas
Passwork admite múltiples sesiones simultáneas:
- El usuario puede estar autenticado en varios dispositivos
- Cada dispositivo tiene su propio par de tokens
- El cierre de sesión en un dispositivo no afecta a los demás
Gestión de sesiones
El usuario puede:
- Ver la lista de sesiones activas
- Terminar una sesión específica
- Terminar todas las sesiones (excepto la actual)
El administrador puede:
- Forzar la terminación de todas las sesiones de un usuario
Recomendaciones de configuración
Alta seguridad
| Parámetro | Valor |
|---|---|
| Access Token | 30 minutos |
| Refresh Token | 4 horas |
- Reautenticación frecuente
- Ventana de ataque corta
- Adecuado para sistemas críticos
Equilibrio entre seguridad y comodidad (predeterminado)
| Parámetro | Valor |
|---|---|
| Access Token | ~2,8 horas |
| Refresh Token | 36 horas |
- Jornada laboral sin reautenticación
- Refresh Token para ~1,5 jornadas laborales
- Adecuado para la mayoría de las organizaciones
Máxima comodidad
| Parámetro | Valor |
|---|---|
| Access Token | 8 horas |
| Refresh Token | 7 días |
- Autenticación una vez por semana
- Adecuado para escenarios de bajo riesgo
- No recomendado para datos críticos