Hop til hovedindhold

Godkendelse og sikkerhed

Libre WebUI bruger lokale brugerkonti med JWT-sessioner. En ny installation tillader altid, at én lokal administrator oprettes. Offentlig registrering af senere lokale konti og OAuth-konti er lukket som standard.

Førstegangsopsætning​

Når databasen ikke har brugere:

  1. Libre WebUI viser førstegangsopsætningen.
  2. Brugeren opretter den første lokale konto.
  3. Kontoen tildeles rollen admin.
  4. Senere offentlig registrering forbliver lukket, medmindre den aktiveres udtrykkeligt.

Eksisterende databaser beholder aktuelle brugere og roller.

Lokale konti​

Lokal registrering kræver:

  • Brugernavn
  • Adgangskode mellem 12 tegn og 72 UTF-8-byte med stort bogstav, lille bogstav og tal
  • Valgfri e-mailadresse

Adgangskoder hashes med bcrypt før lagring. Login- og registreringsruter er hastighedsbegrænsede.

Godkendelse af registrering​

Offentlig registrering giver ikke adgang i sig selv. Hver konto, der oprettes gennem formularen eller en OAuth-udbyder, starter i tilstanden pending og skal godkendes af en administrator før login.

Undtagelsen er startkontoen: den første rigtige konto i en tom database oprettes atomisk som active med rollen admin, så en ny installation får en fungerende administrator. Alle senere registreringer afventer gennemgang.

Hvad en afventende bruger ser:

  • Registreringen lykkes, men returnerer ingen sessionstoken. API'et svarer 202 med approvalRequired: true, og UI'et forklarer, at en administrator skal godkende kontoen.
  • Login med korrekt adgangskode afvises med 403 og koden ACCOUNT_PENDING ("Din konto afventer administratorgodkendelse"). OAuth-login omdirigeres til loginsiden med ?approval=pending.
  • Kontostatus læses igen fra databasen ved hver godkendt anmodning, så en session aldrig kan overleve kontoens status active.

Hvad en administrator ser:

  • Brugeradministration viser kortet Afventende godkendelser med afventende konti, handlingen Aktivér konto og en afvisningshandling. Afvisning betyder sletning; der findes ingen særskilt suspenderet tilstand.
  • Indloggede administratorer får besked i appen med et mærke ved Brugere og en popup ved nye registreringer. Oversigten forespørges omtrent én gang i minuttet (GET /api/users/pending-approvals, kun administratorer).
  • Godkendelse (PATCH /api/users/:id/approve, kun administratorer) registrerer hvem og hvornår. Rollen ændres ikke: kontoen beholder user, indtil den forfremmes. Godkendelsen gælder ved næste loginforsøg; intet skal oprettes igen.

Eksisterende konti påvirkes ikke af en opgradering. Kun konti, der oprettes gennem offentlig registrering efter funktionens indførelse, starter som afventende. Konti oprettet af en administrator er aktive med det samme.

Aktivér offentlig registrering bevidst​

Registrering er deaktiveret som standard. Angiv kun backendvariablen nedenfor i det tidsrum, hvor nye lokale eller OAuth-konti skal accepteres:

ENABLE_SIGNUP=true

Sæt den tilbage til false efter det planlagte registreringsvindue. Eksisterende brugere kan stadig logge ind, og administratorer kan oprette konti, mens offentlig registrering er lukket.

En tom database tillader altid én lokal administrator, selv når ENABLE_SIGNUP=false; OAuth kan ikke bruge startpladsen. Ved en privat fjernudrulning placeres værtsnavnet bag en identitetstilladelsesliste som Cloudflare Access før start, hvorefter den første administrator oprettes gennem den beskyttede rute.

Roller​

RolleFormål
adminInstansadministration, brugeradministration, systemindstillinger og betroet Work-runtime
userNormale flows til chat, model, persona, dokument og indstillinger

Installation, sletning, kopiering, push og aflæsning af modeller er begrænset til administratorer, fordi handlingerne ændrer værtsressourcer.

Work-adgang​

Work er som standard begrænset til administratorer, fordi en valgt model kan køre vilkårlige kommandoer i en administreret container. En administrator kan åbne Work for alle aktive brugere fra fanen Brugeradministration i Indstillinger. Indstillingen bevares efter genstart og gælder straks, også for åbne terminalsessioner. Arbejdsområder med værtsmapper forbliver kun for administratorer, fordi de bind-monterer serverstier. Behandl alle med Work-adgang som betroede runtimeoperatører, ikke kun WebUI-brugere.

Administratorrettigheder kontrolleres mod den aktuelle databaserolle, ikke kun JWT-cachen. Nedgradering tilbagekalder derfor Work-adgang straks. Backend forsøger at afbryde aktive kørsler og stoppe brugerens Work-containere og forhåndsvisninger, men bevarer opgaveregistre og navngivne volumener. Hvis Docker-oprydning mislykkes, forbliver adgangen tilbagekaldt, rolleændringen rapporterer fejlen, og operatøren skal gendanne Docker-adgang og prøve igen.

Sletning af en bruger ødelægger brugerens Work-data. Libre WebUI stopper først administrerede containere og fjerner Work-volumener, derefter konto og databaseposter. Hvis Docker ikke kan bevise, at oprydningen lykkedes, mislykkes kontosletningen, så en administrator kan rette runtimeproblemet og prøve igen.

Grupper og ressourcetilladelser​

Administratorer kan oprette grupper og administrere medlemskab. Grupper er hovedaktører for ressourcetilladelser: ejeren af chat, note, dokument, videnssamling, mappe, persona, prompt, færdighed eller kalender kan give read, write eller admin til en bruger eller gruppe gennem adgangs-API'et. Alle delbare overflader bruger samme dialog (se Deling), og værktøjsservere kan afgrænses tilsvarende. Ressourcer forbliver private som standard; den globale rolle admin giver ikke adgang til andres indhold. Medlemskab evalueres ved anmodningen, så fjernelse tilbagekalder gruppeadgang straks. Visningen "effektiv adgang" forklarer adgang ved at vise rolle, grupper, funktionsadgang og alle tilladelser.

Sikkerhedsrevisionslog​

Sikkerhedsfølsomme handlinger—login og fejl, logout, tilbagekaldte sessioner og tokens samt ændringer af brugere, grupper, tilladelser og tokens—registreres i en separat revisionslog, der kun kan udvides. Detaljer maskeres før lagring: hemmelighedslignende nøgler fjernes, og payloadstørrelser begrænses, så adgangskoder, tokens og promptindhold aldrig kommer i loggen. Gruppe- og tilladelsesændringer skriver revisionshændelsen i samme databasetransaktion. Standardopbevaring er 180 dage (AUDIT_RETENTION_DAYS).

Sessioner​

Backend signerer JWT med JWT_SECRET. Angiv en stabil hemmelighed i produktion:

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

Ændring af JWT_SECRET ugyldiggør eksisterende sessioner. Lokale og OAuth-login-tokens bruger JWT_EXPIRES_IN, standard 7d; ændringen påvirker nye sessioner. WebSocket-forbindelser udveksler den vedvarende token med en kortlivet engangsbillet og lukkes, når den underliggende session udløber.

Hvert login opretter også en serversessionspost bundet til JWT. Indstillinger → Sessioner viser enheder, loginmetode, første og seneste aktivitet samt udløb. Tilbagekaldelse eller Log andre sessioner ud ugyldiggør token straks på alle replikaer og lukker aktive WebSocket-forbindelser. Ældre tokens uden sessions-ID forbliver gyldige til udløb, men handlingen fra et nyt login angiver også en kontogrænse, der afviser dem.

Tofaktorgodkendelse og passkeys​

Indstillinger → Sessioner administrerer både andenfaktorer og adgangskodefrit login:

  • Godkendelsesapp (TOTP). Registrering viser en base32-hemmelighed og et otpauth://-link til enhver godkendelsesapp. Den første sekscifrede kode aktiverer funktionen og viser ti engangsgendannelseskoder. Derefter returnerer adgangskodelogin en kortlivet udfordring i stedet for en session, og POST /api/auth/mfa/verify fuldfører login med TOTP- eller gendannelseskode. Tidssteppet for hver accepteret kode registreres, så koden ikke kan genafspilles. Gendannelseskoder gemmes kun som nøglede envejsopslagstokens og virker præcis én gang. Deaktivering eller nye koder kræver genbekræftelse af faktoren.
  • Passkeys (WebAuthn). Log ind med passkey udfører adgangskodefrit login med en registrerbar legitimation. Brugerverifikation via skærmlås, biometri eller PIN kræves ved registrering og login. Attestation accepteres som none, ES256 og EdDSA understøttes, og legitimationsmateriale krypteres ved lagring med ID'et som nøglede opslagstoken. Udfordringer bruges én gang og udløber efter fem minutter; en signaturtæller, der ikke stiger, afvises som klonsignal. Passkeys kræver sikker HTTPS-origin eller localhost under udvikling. Angiv WEBAUTHN_RP_ID ved flere værtsnavne.

MFA-udfordringstoken efter korrekt adgangskode signeres med en hemmelighed, der er afledt af, men forskellig fra JWT_SECRET. Den kan aldrig godkende en API-anmodning, er bundet til én konto og ét formål og forbruges ved succes.

Administratorer kan kræve en anden faktor for alle konti (Brugere → tofaktorpolitikkortet eller MFA_REQUIRED_MODE=required). Brugere uden faktor føres gennem registrering ved næste login før sessionsudstedelse. Administratorer kan nulstille TOTP til kontogendannelse; passkeys efterlades, fordi brugeren administrerer dem. Registrering, aktivering, verifikationsfejl, deaktivering, politikændringer, tilføjelse/fjernelse af passkey og administratornulstillinger revisionslogges.

MFA gælder adgangskodelogin. OAuth og OIDC bruger identitetsudbyderens andenfaktor og udfordres ikke igen. API-tokens påvirkes ikke, fordi de aldrig bruger sessionsgodkendelse.

API-tokens​

Indstillinger → API-nøgler opretter personlige adgangstokens med præfikset lwk_. Hemmeligheden vises én gang og gemmes kun som hash. Hver token har en udtrykkelig omfangsliste (chat, models, documents, notes, personas, media, work, admin); backend tilknytter hver rutefamilie til et omfang, så en notetoken ikke kan nå chats eller administration, og sessionsadministration kan aldrig nås med token. Tokens understøtter valgfrit udløb, sporer seneste brug, kan tilbagekaldes og hastighedsbegrænses pr. token på tværs af replikaer. Admin-tokens kan kun oprettes af administratorer og kræver stadig adminrollen ved brug. En token med chat er også nøglen til det OpenAI-kompatible offentlige /v1-API.

Cloudflare Turnstile​

Turnstile beskytter adgangskodelogin og registrering, når begge nøgler er konfigureret:

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

Frontend tildeler separate handlinger login og signup. Backend verificerer token med Cloudflare og afviser et svar, hvis værtsnavn eller handling ikke matcher. BASE_URL angiver det forventede værtsnavn, når TURNSTILE_EXPECTED_HOSTNAME ikke angives.

Hvis en af nøglerne mangler, deaktiveres Turnstile.

GitHub OAuth​

Konfigurér:

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

GitHub OAuth opretter lokale brugere med brugernavne, der starter med gh_, og rollen user som standard.

Hugging Face OAuth​

Konfigurér:

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

Hugging Face OAuth opretter lokale brugere med brugernavne, der starter med hf_, og rollen user som standard.

Begge OAuth-udbydere bruger en kryptografisk tilfældig state bundet til en kortlivet HttpOnly-, SameSite-cookie. Callbacken afviser manglende eller afvigende tilstand. Efter vellykket callback returneres JWT i en 60-sekunders HttpOnly-cookie, der udveksles og ryddes straks; bearer-tokens placeres aldrig i callback-URL'er, browserhistorik eller referrer-headere.

Omdirigeringer og CORS​

Angiv BASE_URL til callbackstandard og CORS_ORIGIN til browseradgang:

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

Medtag Vites udviklings-origin ved lokal udvikling:

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

Demotilstand​

Demotilstand er en frontend-forhåndsvisning. Den forudfylder deaktiverede demooplysninger og bruger simulerede API-svar. Det er ikke godkendelse til produktion.

Sikkerhedstjekliste​

  • Angiv en stærk JWT_SECRET.
  • Behold DATA_DIR på vedvarende, adgangskontrolleret lager.
  • Sikkerhedskopiér ENCRYPTION_KEY sammen med databasen.
  • Konfigurér Turnstile til offentlig registrering.
  • Brug HTTPS til offentlige udrulninger.
  • Begræns udbydernøgler til det mindst nødvendige omfang.
  • Hold OAuth-callback-URL'er nøjagtige.
  • Giv kun Work-adgang til personer, der er betroet til at betjene backendens containerruntime.

Relateret dokumentation​