Single sign-on
Libre WebUI ondersteunt OAuth-aanmelding met GitHub en Hugging Face, plus elke OpenID Connect-provider via de algemene OIDC-integratie. OAuth-gebruikers worden nog steeds als lokale Libre WebUI-gebruikers opgeslagen en krijgen standaard de rol user (OIDC kan optioneel rollen en groepen uit claims toewijzen).
GitHub OAuth
Maak een OAuth-app in GitHub Developer Settings.
Lokale callback-URL:
http://localhost:3001/api/auth/oauth/github/callback
Callback-URL voor productie:
https://your-domain.example/api/auth/oauth/github/callback
Backend-.env:
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback
GitHub OAuth vraagt het bereik user:email aan. Nieuwe gebruikers krijgen een gebruikersnaam met het voorvoegsel gh_.
Hugging Face OAuth
Maak een OAuth-app in de instellingen van Hugging Face.
Lokale callback-URL:
http://localhost:3001/api/auth/oauth/huggingface/callback
Callback-URL voor productie:
https://your-domain.example/api/auth/oauth/huggingface/callback
Backend-.env:
HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback
Nieuwe gebruikers krijgen een gebruikersnaam met het voorvoegsel hf_.
Algemene OIDC
Elke provider met een OpenID Connect-discoverydocument werkt: Keycloak, Authentik, Authelia, Okta, Entra ID, Google Workspace en andere. De stroom gebruikt PKCE (S256), een CSRF-status en een nonce die wordt gecontroleerd in het ID-token waarvan de handtekening is geverifieerd; ondertekeningssleutels zijn afkomstig uit de JWKS van de provider.
Registreer een vertrouwelijke client met deze callback-URL:
https://your-domain.example/api/auth/oauth/oidc/callback
Backend-.env:
OIDC_ISSUER_URL=https://id.example.com/realms/main
OIDC_CLIENT_ID=libre-webui
OIDC_CLIENT_SECRET=...
OIDC_DISPLAY_NAME=Example SSO
Optionele beleidsregels:
# 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
Identiteiten worden gekoppeld via de stabiele claim sub, zodat een hernoemd provideraccount zijn Libre-account behoudt. Nieuwe gebruikers krijgen een gebruikersnaam met het voorvoegsel oidc_ wanneer registratie dat toestaat. Een e-mailadres dat al bij een niet-gekoppeld lokaal account hoort, wordt geweigerd en niet stilzwijgend samengevoegd. Met OIDC_SYNC_GROUPS=true wordt het lidmaatschap van elke Libre-groep waarvan de naam overeenkomt met een claimwaarde voor OIDC-gebruikers door claims bepaald. Maak de overeenkomende groepen daarom eerst aan via het tabblad Gebruikersbeheer in Settings.
Gedeelde instellingen
Stel de openbare backend-URL in:
BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
Als callback-URL's niet expliciet zijn ingesteld, bouwt Libre WebUI standaardwaarden op basis van BASE_URL.
Beperkingen
Libre WebUI biedt momenteel geen SAML- of SCIM-provisioning. Toegestane domeinen en toewijzing van rollen/groepen zijn alleen beschikbaar voor de algemene OIDC-provider; GitHub- en Hugging Face-gebruikers worden altijd met de rol user aangemaakt en via de beheerinterface beheerd.
Problemen oplossen
OAuth-knop doet niets
Controleer of de client-ID en het geheim van de provider zijn ingesteld en of de backend opnieuw is gestart.
Provider weigert callback
De callback-URL in het dashboard van de provider moet exact overeenkomen met de URL die Libre WebUI gebruikt.
Gebruiker krijgt normale rechten
OAuth-gebruikers worden standaard als user aangemaakt. Promoveer gebruikers zo nodig via de beheerinterface.