Saltar al contenido principal

Autenticación y seguridad

Libre WebUI utiliza cuentas locales con sesiones JWT. Una instalación nueva siempre permite crear un primer administrador local. El registro público de todas las cuentas locales u OAuth posteriores está cerrado de forma predeterminada.

Configuración inicial​

Cuando la base de datos no contiene usuarios:

  1. Libre WebUI muestra el flujo de configuración inicial.
  2. El usuario crea la primera cuenta local.
  3. Se le asigna el rol admin.
  4. Todo registro público posterior permanece cerrado salvo que se habilite expresamente.

Las bases existentes conservan sus usuarios y roles.

Cuentas locales​

El registro local exige:

  • Nombre de usuario
  • Contraseña de entre 12 caracteres y 72 bytes UTF-8, con mayúscula, minúscula y número
  • Correo electrónico opcional

Las contraseñas se cifran con bcrypt antes de almacenarlas. Las rutas de inicio de sesión y registro tienen límites de frecuencia.

Aprobación del registro​

Registrarse públicamente no concede acceso por sí solo. Toda cuenta creada mediante el formulario público o un proveedor OAuth empieza en estado pending y debe ser aprobada por un administrador antes de iniciar sesión.

La única excepción es el arranque: la primera cuenta real de una base vacía se crea de forma atómica como active con rol admin, de modo que una instalación nueva produzca un administrador operativo. Todas las posteriores esperan revisión.

Lo que ve un usuario pendiente:

  • El registro se completa, pero no devuelve token de sesión. La API responde 202 con approvalRequired: true y la interfaz explica que un administrador debe aprobar la cuenta.
  • Un inicio con credenciales correctas se rechaza con 403 y ACCOUNT_PENDING ("Your account is waiting for administrator approval"). OAuth vuelve a la página de inicio con ?approval=pending.
  • El estado se vuelve a leer de la base en cada solicitud autenticada, por lo que una sesión nunca puede sobrevivir al estado active de la cuenta.

Lo que ve un administrador:

  • Gestión de usuarios muestra una tarjeta Aprobaciones pendientes con las cuentas en espera, una acción Activar cuenta y otra para rechazar. Rechazar elimina la cuenta; no existe un estado suspendido aparte.
  • Los administradores reciben notificaciones mientras están conectados: insignia en Usuarios y aviso cuando llegan registros. El resumen se consulta aproximadamente una vez por minuto (GET /api/users/pending-approvals, solo administradores).
  • La aprobación (PATCH /api/users/:id/approve, solo administradores) registra quién aprobó y cuándo. No cambia el rol: la cuenta conserva user hasta que un administrador la ascienda. Entra en vigor en el siguiente intento de inicio; no hay que recrear nada.

Las cuentas existentes no se ven afectadas por una actualización: solo las creadas por registro público después de incorporar la función comienzan pendientes. Las creadas por un administrador están activas inmediatamente.

Habilitar deliberadamente el registro público​

El registro está deshabilitado de forma predeterminada. Define esta variable del backend solo durante el periodo en que deban aceptarse cuentas locales u OAuth nuevas:

ENABLE_SIGNUP=true

Devuélvela a false después de la ventana planificada. Los usuarios existentes pueden seguir iniciando sesión y los administradores creando cuentas con el registro cerrado.

Una base vacía siempre permite un administrador local incluso con ENABLE_SIGNUP=false; OAuth no puede ocupar esa plaza. Para un despliegue remoto privado, protege el host con una lista de identidades como Cloudflare Access antes de iniciar y crea el administrador por esa ruta protegida.

Roles​

RolFinalidad
adminAdministración de instancia y usuarios, ajustes del sistema y operación de confianza del entorno Work
userFlujos normales de chat, modelos, personas, documentos y ajustes

La instalación, eliminación, copia, publicación y descarga de modelos se limita a administradores porque modifica recursos del host.

Acceso a Work​

Work está restringido a administradores de forma predeterminada porque permite que un modelo ejecute comandos arbitrarios en un contenedor administrado. Un administrador puede abrirlo a todos los usuarios activos desde la pestaña Gestión de usuarios en Configuración; el ajuste persiste y se aplica de inmediato, incluso a terminales abiertos. Los espacios basados en carpetas del host siguen siendo solo para administradores porque montan rutas del servidor. Considera a quien tenga Work un operador de confianza del entorno, no solo usuario de la WebUI.

La autorización se comprueba con el rol actual en la base, no solo el guardado en JWT. Rebajar a un administrador revoca Work inmediatamente. El backend intenta abortar ejecuciones activas y detener contenedores y vistas previas, conservando registros y volúmenes. Si falla la limpieza Docker, el acceso sigue revocado, el cambio informa del fallo y el operador debe restaurar Docker y reintentar.

Eliminar un usuario destruye sus datos de Work. Libre WebUI detiene contenedores y elimina volúmenes antes de borrar cuenta y registros. Si Docker no puede demostrar que la limpieza terminó, la eliminación falla para que un administrador corrija el entorno.

Grupos y permisos de recursos​

Los administradores crean grupos y gestionan miembros desde la pestaña Gestión de usuarios en Configuración. Los grupos son principales de permisos: el propietario de un chat, nota, documento, colección, carpeta, persona, prompt, habilidad o calendario puede conceder read, write o admin a un usuario o grupo mediante la API. Todas las superficies usan el mismo diálogo (consulta Uso compartido), y los servidores de herramientas se pueden limitar igual. Los recursos son privados de forma predeterminada: el rol global admin no accede a contenido ajeno. La pertenencia se evalúa en cada solicitud; retirar un miembro revoca inmediatamente el acceso del grupo. La vista «acceso efectivo» de la pestaña Gestión de usuarios en Configuración explica por qué un usuario accede enumerando rol, grupos, funciones y permisos.

Registro de auditoría de seguridad​

Las acciones sensibles —inicios y fallos, cierres, revocaciones, cambios de usuarios, grupos, permisos y tokens— se registran en un diario de solo adición separado del análisis de uso. Los detalles se censuran antes de guardarse: se eliminan claves parecidas a secretos y se limitan cargas, así que contraseñas, tokens y prompts nunca entran. Los cambios de grupos y permisos escriben su evento en la misma transacción, por lo que no existe cambio sin rastro. Los administradores consultan el diario desde la pestaña Gestión de usuarios en Configuración; la retención predeterminada es 180 días (AUDIT_RETENTION_DAYS).

Sesiones​

El backend firma los JWT con JWT_SECRET. Define un secreto estable en producción:

JWT_SECRET=replace-with-a-long-random-secret

Cambiar JWT_SECRET invalida las sesiones. Los tokens locales y OAuth usan JWT_EXPIRES_IN, con valor predeterminado 7d; cambiarlo afecta a sesiones nuevas. Las conexiones WebSocket canjean el token duradero por un ticket de un solo uso y corta duración y se cierran al caducar la sesión subyacente.

Cada inicio crea además un registro de sesión en el servidor vinculado al JWT. Ajustes → Sesiones enumera dispositivos, método, primera y última actividad y caducidad. Revocar allí (o «Cerrar las demás sesiones») invalida el token inmediatamente en todas las réplicas y cierra WebSockets; cerrar sesión revoca la actual. Los tokens anteriores sin ID siguen hasta caducar, salvo que «Cerrar las demás sesiones» desde un inicio nuevo también marque un límite por cuenta que los rechaza.

Autenticación de dos factores y llaves de acceso​

Ajustes → Sesiones gestiona factores y acceso sin contraseña:

  • Aplicación de autenticación (TOTP). El alta muestra un secreto base32 y enlace otpauth://; confirmar el primer código de 6 dígitos lo activa y revela diez códigos de recuperación de un uso. Después, el inicio con contraseña devuelve un desafío breve y POST /api/auth/mfa/verify lo completa con TOTP o recuperación. Se registra el intervalo de cada código para evitar repeticiones; los de recuperación solo se guardan como tokens de búsqueda unidireccionales con clave y funcionan una vez. Deshabilitar o regenerarlos requiere demostrar de nuevo un factor.
  • Llaves de acceso (WebAuthn). «Iniciar sesión con una llave» utiliza una credencial detectable sin contraseña; exige verificar al usuario (bloqueo, biometría o PIN) al registrarse y entrar. Se acepta atestación none, se admiten ES256 y EdDSA y el material se cifra en reposo con el ID como token de búsqueda con clave. Los desafíos son de un uso y caducan en cinco minutos; un contador no nulo que no avance se rechaza como indicio de clonación. Requieren origen HTTPS seguro o localhost en desarrollo; define WEBAUTHN_RP_ID si se accede por varios hosts.

El token de desafío MFA se firma con un secreto derivado pero distinto de JWT_SECRET: nunca autentica API, está ligado a una cuenta y finalidad y se consume al acertar.

Los administradores pueden exigir factor para todas las cuentas (Usuarios → tarjeta de política, o MFA_REQUIRED_MODE=required). Quien no lo tenga debe darlo de alta en el siguiente inicio antes de recibir sesión. Los administradores pueden restablecer TOTP para recuperar cuentas; las llaves permanecen porque el usuario las gestiona. Altas, activación, fallos, deshabilitación, políticas, registro/eliminación de llaves y restablecimientos quedan auditados.

MFA se aplica al inicio con contraseña. OAuth y OIDC confían en el factor del proveedor y no desafían de nuevo. Los tokens de API no se ven afectados.

Tokens de API​

Ajustes → Claves de API crea tokens personales (prefijo lwk_) para uso programático. El secreto se muestra una vez y solo se guarda su hash. Cada token tiene ámbitos explícitos (chat, models, documents, notes, personas, media, work, admin); el backend asigna cada familia a un ámbito, por lo que uno de notas no toca chats ni administración, y la gestión de sesiones nunca acepta tokens. Admiten caducidad, registran último uso, pueden revocarse y tienen límite por token entre réplicas. Solo administradores crean ámbito admin y la cuenta debe seguir siéndolo al usarlo. El ámbito chat también es la clave de la API pública /v1 compatible con OpenAI.

Cloudflare Turnstile​

Turnstile protege el inicio y registro cuando se configuran ambas claves:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=chat.example.com

El frontend asigna acciones login y signup distintas. El backend verifica el token con Cloudflare y rechaza respuestas cuyo host o acción no coincidan. BASE_URL proporciona el host esperado cuando TURNSTILE_EXPECTED_HOSTNAME no está definida.

Si falta una clave, Turnstile se deshabilita.

OAuth de GitHub​

Configura:

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback

El flujo crea usuarios locales con nombres prefijados por gh_ y rol user predeterminado.

OAuth de Hugging Face​

Configura:

HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

El flujo crea usuarios locales con nombres prefijados por hf_ y rol user predeterminado.

Ambos proveedores utilizan un state aleatorio seguro ligado a una cookie HttpOnly SameSite breve. La devolución rechaza estados ausentes o distintos. Tras el éxito, el JWT vuelve al frontend en una cookie HttpOnly de 60 segundos que se canjea y elimina de inmediato; los tokens Bearer nunca aparecen en URL, historial ni cabeceras de referencia.

Redirecciones y CORS​

Define BASE_URL para valores predeterminados y CORS_ORIGIN para acceso del navegador:

BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example

En desarrollo, incluye el origen de Vite:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

Modo de demostración​

Es un modo de vista previa del frontend. Rellena credenciales deshabilitadas y usa API simuladas. No es autenticación de producción.

Lista de seguridad​

  • Define un JWT_SECRET robusto.
  • Guarda DATA_DIR en almacenamiento persistente con acceso controlado.
  • Copia ENCRYPTION_KEY con la base de datos.
  • Configura Turnstile para registro público.
  • Utiliza HTTPS en despliegues públicos.
  • Limita las claves de proveedores al ámbito mínimo.
  • Mantén exactas las URL de devolución OAuth.
  • Concede Work solo a personas de confianza para operar el entorno de contenedores.

Documentación relacionada​