Inicio de sesión único
Libre WebUI admite el inicio de sesión OAuth con GitHub y Hugging Face, además de cualquier proveedor OpenID Connect mediante la integración OIDC genérica. Los usuarios OAuth siguen almacenándose como usuarios locales de Libre WebUI y reciben el rol user de forma predeterminada (OIDC puede asignar opcionalmente roles y grupos desde las claims).
OAuth de GitHub
Crea una aplicación OAuth en los ajustes para desarrolladores de GitHub.
URL de callback local:
http://localhost:3001/api/auth/oauth/github/callback
URL de callback de producción:
https://your-domain.example/api/auth/oauth/github/callback
Archivo .env del backend:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
OAuth de GitHub solicita el ámbito user:email. Los nombres de usuario nuevos reciben el prefijo gh_.
OAuth de Hugging Face
Crea una aplicación OAuth en los ajustes de Hugging Face.
URL de callback local:
http://localhost:3001/api/auth/oauth/huggingface/callback
URL de callback de producción:
https://your-domain.example/api/auth/oauth/huggingface/callback
Archivo .env del backend:
HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback
Los nombres de usuario nuevos reciben el prefijo hf_.
OIDC genérico
Funciona cualquier proveedor con documento de descubrimiento OpenID Connect: Keycloak, Authentik, Authelia, Okta, Entra ID, Google Workspace y otros. El flujo utiliza PKCE (S256), estado CSRF y un nonce verificado dentro del token de ID cuya firma se ha comprobado; las claves de firma proceden del JWKS del proveedor.
Registra un cliente confidencial con esta URL de callback:
https://your-domain.example/api/auth/oauth/oidc/callback
Archivo .env del backend:
OIDC_ISSUER_URL=https://id.example.com/realms/main
OIDC_CLIENT_ID=libre-webui
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Example SSO
Políticas opcionales:
# Require a verified email in one of these domains
OIDC_ALLOWED_EMAIL_DOMAINS=example.com,example.org
# Grant/remove the admin role based on a group claim on every login
OIDC_GROUP_CLAIM=groups
OIDC_ADMIN_GROUPS=libre-admins
# Reconcile Libre group memberships with the group claim on every login
OIDC_SYNC_GROUPS=true
Las identidades se vinculan mediante la claim estable sub, por lo que una cuenta renombrada
en el proveedor conserva su cuenta Libre. Los nombres nuevos reciben el prefijo oidc_
cuando el registro lo permite. Un correo que ya pertenezca a una cuenta local no vinculada
se rechaza en lugar de fusionarse silenciosamente. Con OIDC_SYNC_GROUPS=true, la pertenencia
a cada grupo Libre cuyo nombre coincida con un valor de claim queda gobernada por dicha claim
para usuarios OIDC; crea primero los grupos correspondientes en la pestaña Gestión de usuarios de Configuración.
Ajustes compartidos
Define la URL pública del backend:
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
Si no se definen explícitamente las URL de callback, Libre WebUI crea los valores predeterminados a partir de BASE_URL.
Límites
Libre WebUI no ofrece actualmente SAML ni aprovisionamiento SCIM. Las listas de dominios permitidos y la asignación de roles y grupos solo están disponibles para el proveedor OIDC genérico; los usuarios de GitHub y Hugging Face siempre se crean con el rol user y se gestionan desde la interfaz de administración.
Solución de problemas
El botón OAuth no hace nada
Confirma que el ID y el secreto de cliente estén definidos y que el backend se haya reiniciado.
El proveedor rechaza el callback
La URL configurada en el panel del proveedor debe coincidir exactamente con la usada por Libre WebUI.
El usuario obtiene permisos normales
Los usuarios OAuth se crean como user de forma predeterminada. Promuévelos desde la interfaz de administración si es necesario.