Single Sign-On
Libre WebUI supporta l'accesso OAuth con GitHub e Hugging Face, oltre a qualsiasi provider OpenID Connect tramite l'integrazione OIDC generica. Gli utenti OAuth vengono comunque archiviati come utenti locali di Libre WebUI e ricevono per impostazione predefinita il ruolo user (OIDC può facoltativamente associare ruoli e gruppi dalle attestazioni).
OAuth con GitHub
Crea un'app OAuth nelle Impostazioni sviluppatore di GitHub.
URL di callback locale:
http://localhost:3001/api/auth/oauth/github/callback
URL di callback di produzione:
https://your-domain.example/api/auth/oauth/github/callback
File .env del backend:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
OAuth di GitHub richiede l'ambito user:email. I nuovi utenti vengono creati con nomi utente preceduti da gh_.
OAuth con Hugging Face
Crea un'app OAuth nelle impostazioni di Hugging Face.
URL di callback locale:
http://localhost:3001/api/auth/oauth/huggingface/callback
URL di callback di produzione:
https://your-domain.example/api/auth/oauth/huggingface/callback
File .env del backend:
HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback
I nuovi utenti vengono creati con nomi utente preceduti da hf_.
OIDC generico
Funziona qualsiasi provider dotato di un documento di individuazione OpenID Connect: Keycloak, Authentik, Authelia, Okta, Entra ID, Google Workspace e altri. Il flusso usa PKCE (S256), lo stato CSRF e un nonce verificato all'interno del token ID con firma controllata; le chiavi di firma provengono dal JWKS del provider.
Registra un client riservato con questo URL di callback:
https://your-domain.example/api/auth/oauth/oidc/callback
File .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
Regole facoltative:
# 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
Le identità vengono collegate tramite l'attestazione stabile sub, quindi un account del provider
rinominato mantiene il proprio account Libre. Quando la registrazione lo consente, i nuovi utenti
vengono creati con nomi utente preceduti da oidc_. Un indirizzo email già appartenente a un account
locale non collegato viene rifiutato anziché unito automaticamente. Con
OIDC_SYNC_GROUPS=true, per gli utenti OIDC l'appartenenza a ogni gruppo Libre il cui nome corrisponde
a un valore dell'attestazione è determinata da quest'ultima: crea prima i gruppi corrispondenti
nella scheda Gestione utenti in Impostazioni.
Impostazioni condivise
Imposta l'URL pubblico del backend:
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
Se gli URL di callback non vengono impostati esplicitamente, Libre WebUI crea i valori predefiniti a partire da BASE_URL.
Limiti
Libre WebUI attualmente non offre il provisioning SAML o SCIM. Gli elenchi di domini consentiti e l'associazione di ruoli/gruppi sono disponibili solo per il provider OIDC generico; gli utenti GitHub e Hugging Face vengono sempre creati con il ruolo user e gestiti dall'interfaccia di amministrazione.
Risoluzione dei problemi
Il pulsante OAuth non fa nulla
Verifica che l'ID client e il secret del provider siano impostati e che il backend sia stato riavviato.
Il provider rifiuta la callback
L'URL di callback nel pannello del provider deve corrispondere esattamente a quello usato da Libre WebUI.
L'utente riceve permessi normali
Gli utenti OAuth vengono creati come user per impostazione predefinita. Se necessario, promuovili dall'interfaccia di amministrazione.