Ga naar hoofdinhoud

Authenticatie en beveiliging

Libre WebUI gebruikt lokale accounts met JWT-sessies. Een nieuwe installatie laat altijd één lokale beheerder initialiseren. Openbare registratie voor latere lokale of OAuth-accounts staat standaard dicht.

Eerste installatie​

  1. Libre WebUI toont de eerste configuratie.
  2. De eerste lokale account wordt gemaakt.
  3. Die krijgt rol admin.
  4. Latere registratie blijft dicht tot expliciet ingeschakeld.

Bestaande databases behouden gebruikers en rollen.

Lokale accounts​

Vereist gebruikersnaam, optionele e-mail en wachtwoord van 12 tekens tot 72 UTF-8-bytes met hoofdletter, kleine letter en cijfer. Wachtwoorden worden met bcrypt gehasht; routes zijn rate-limited.

Registratiegoedkeuring​

Openbare registratie geeft niet direct toegang. Accounts beginnen als pending en moeten worden goedgekeurd.

Uitzondering: het eerste echte account in lege database wordt atomair active met admin.

Een wachtende gebruiker:

  • krijgt 202 met approvalRequired: true, geen sessietoken;
  • correct wachtwoord wordt geweigerd met 403 en ACCOUNT_PENDING ("Je account wacht op goedkeuring"); OAuth keert terug met ?approval=pending;
  • status wordt bij elke aanvraag opnieuw gelezen.

Beheerder ziet Wachtende goedkeuringen, Account activeren en weigeren (verwijderen). Badge/toast en ongeveer minuutpoll via GET /api/users/pending-approvals. PATCH /api/users/:id/approve registreert wie/wanneer maar behoudt rol user.

Bestaande accounts veranderen niet; door beheerder gemaakte accounts zijn direct actief.

Openbare registratie bewust inschakelen​

ENABLE_SIGNUP=true

Zet na het venster terug op false. Bestaande gebruikers kunnen blijven aanmelden en beheerders accounts maken.

Een lege database laat altijd één lokale beheerder toe, ook met ENABLE_SIGNUP=false; OAuth kan die plek niet gebruiken. Bescherm remote bootstrap met een identiteitslaag zoals Cloudflare Access.

Rollen​

RolDoel
adminInstantie, gebruikers, systeem en vertrouwde Work-runtime
userGewone chat-, model-, persona-, document- en instellingsstromen

Modelinstallatie, verwijdering, kopie, push en unload zijn admin-only vanwege hostresources.

Work-toegang​

Standaard admin-only omdat modellen willekeurige commando's in containers uitvoeren. Een beheerder kan alle actieve gebruikers toelaten; de instelling blijft en geldt meteen, ook voor terminalsessies. Hostmappen blijven admin-only. Behandel iedereen als vertrouwde runtimeoperator.

Autorisatie leest actuele databaserol, niet alleen JWT. Degraderen trekt meteen in; backend probeert runs te stoppen en containers/préviews te sluiten met behoud van records/volumes. Docker-fout herstelt toegang niet.

Gebruiker verwijderen vernietigt diens Work-data. Eerst containers en volumes; kan cleanup niet worden bewezen, dan mislukt verwijderen.

Groepen en rechten​

Beheerders maken groepen. Eigenaren van chat, notitie, document, collectie, map, persona, prompt, vaardigheid of agenda kunnen read, write, admin geven aan gebruiker/groep via hetzelfde dialoog (Delen). Toolservers kunnen ook zo worden begrensd. Resources zijn privé; global admin geeft geen toegang tot andermans inhoud. Lidmaatschap wordt per aanvraag bepaald. Effectieve toegang toont reden.

Beveiligingsaudit​

Aanmeldingen, fouten, afmeldingen, intrekkingen en wijzigingen aan gebruikers, groepen, rechten en tokens komen in append-onlylog naast gebruiksanalyse. Gevoelige sleutels en grote payloads worden verwijderd; wachtwoorden, tokens en prompts komen niet in log. Wijziging en audit staan in dezelfde transactie. Standaard 180 dagen (AUDIT_RETENTION_DAYS).

Sessies​

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

JWT_SECRET wijzigen maakt sessies ongeldig. JWT_EXPIRES_IN standaard 7d geldt voor nieuwe sessies. WebSocket gebruikt kort monousoticket.

Elke login maakt server-side sessierecord. Instellingen → Sessies toont apparaat, methode, activiteit en verval. Intrekken of andere sessies afmelden geldt direct op alle replica's en sluit WebSockets. Oudere tokens zonder sessie-ID blijven tot verval, behalve accountcutoff door "andere sessies".

Twee-factor en passkeys​

  • Authenticator (TOTP). Toont base32 en otpauth://; bevestiging activeert en toont tien herstelcodes. Daarna geeft wachtwoord een korte challenge en POST /api/auth/mfa/verify voltooit. Timestep voorkomt replay; herstelcodes zijn eenmalige unidirectionele tokens. Uitschakelen/regenereren vereist opnieuw bewijs.
  • Passkeys (WebAuthn). Wachtwoordloos met vindbare referentie en gebruikersverificatie. Attestation none, ES256/EdDSA, versleuteld materiaal, ID als zoektoken. Challenge eenmalig vijf minuten; niet-oplopende teller is kloonsignaal. HTTPS of localhost; WEBAUTHN_RP_ID bij meerdere hosts.

MFA-challengetoken gebruikt afgeleid maar apart geheim van JWT_SECRET, kan API niet authenticeren en wordt verbruikt.

Beheerders kunnen verplichten met MFA_REQUIRED_MODE=required. Gebruikers worden bij volgende login begeleid. Admin kan TOTP resetten; passkeys blijven bij gebruiker. Alles wordt geaudit.

MFA geldt voor wachtwoord; OAuth/OIDC vertrouwt provider. API-tokens niet betrokken.

API-tokens​

Instellingen → API-sleutels maakt persoonlijke tokens met lwk_. Geheim één keer zichtbaar, alleen hash opgeslagen. Scopes: chat, models, documents, notes, personas, media, work, admin. Routefamilies vereisen scope; sessiebeheer nooit via token. Verval, laatste gebruik, intrekken en rate-limit. Adminscope vereist actuele adminrol. chat is ook sleutel voor openbare /v1-API.

Cloudflare Turnstile​

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

Frontend gebruikt login en signup; backend controleert host/actie. BASE_URL levert host als TURNSTILE_EXPECTED_HOSTNAME ontbreekt. Zonder beide sleutels uit.

GitHub OAuth​

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

Maakt lokale gh_-gebruikers met user.

Hugging Face OAuth​

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

Maakt hf_-gebruikers met user.

Beide gebruiken willekeurige state in korte HttpOnly SameSite-cookie. Callback weigert mismatch. JWT keert in 60-seconden HttpOnly-cookie terug, wordt omgewisseld en gewist; Bearer staat nooit in URL, geschiedenis of referrer.

Redirects en CORS​

Stel CORS_ORIGIN in voor browsertoegang:

BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example
CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

Demomodus​

Frontendvoorbeeld met ingevulde referenties en mocks, geen productieauthenticatie.

Beveiligingslijst​

  • Sterke JWT_SECRET.
  • DATA_DIR persistent en beschermd.
  • Back-up ENCRYPTION_KEY.
  • Turnstile voor publiek.
  • HTTPS.
  • Minimale providerscopes.
  • Exacte OAuth-callbacks.
  • Work alleen vertrouwde operators.

Gerelateerde documenten​