Ugrás a fő tartalomra

Hitelesítés és biztonság

A Libre WebUI helyi felhasználói fiókokat használ JWT-munkamenetekkel. Egy új telepítés mindig engedélyezi egy helyi rendszergazda kezdeti létrehozását. Minden későbbi helyi vagy OAuth-fiók nyilvános regisztrációja alapértelmezés szerint zárva van.

Első beállítás​

Ha az adatbázisban nincs felhasználó:

  1. A Libre WebUI megjeleníti az első beállítási folyamatot.
  2. A felhasználó létrehozza az első helyi fiókot.
  3. A fiók az admin szerepkört kapja.
  4. Minden későbbi nyilvános regisztráció zárva marad, hacsak nincs kifejezetten engedélyezve.

A meglévő adatbázisok megtartják jelenlegi felhasználóikat és szerepköreiket.

Helyi fiókok​

A helyi regisztrációhoz szükséges:

  • Felhasználónév
  • 12 karakter és 72 UTF-8 bájt közötti jelszó nagybetűvel, kisbetűvel és számmal
  • Opcionális e-mail-cím

A jelszavak tárolás előtt bcrypttel hashelődnek. A bejelentkezési és regisztrációs útvonalak sebességkorlátozottak.

Regisztráció jóváhagyása​

A nyilvános regisztráció önmagában nem biztosít hozzáférést. A nyilvános regisztrációs űrlapon vagy OAuth-szolgáltatón keresztül létrehozott minden fiók pending állapotban indul, és bejelentkezés előtt rendszergazdai jóváhagyást igényel.

Az egyetlen kivétel a kezdeti létrehozás: az üres adatbázis első valódi fiókja atomi módon active állapotban, admin szerepkörrel jön létre, így az új telepítés működő rendszergazdát eredményez. Minden későbbi regisztráció felülvizsgálatra vár.

Amit a függő felhasználó lát:

  • A regisztráció sikeres, de nem ad vissza munkamenettokent. Az API 202 választ ad approvalRequired: true értékkel, a felület pedig jelzi, hogy rendszergazdának kell jóváhagynia a fiókot.
  • A helyes hitelesítő adatokkal végzett jelszavas bejelentkezés 403 és ACCOUNT_PENDING kóddal ("Your account is waiting for administrator approval") elutasításra kerül. Az OAuth-bejelentkezés ?approval=pending paraméterrel visszairányít a bejelentkezési oldalra.
  • A fiókállapot minden hitelesített kérésnél újra beolvasódik az adatbázisból, így a munkamenet soha nem élhet tovább a fiók active állapotánál.

Amit a rendszergazda lát:

  • A Felhasználókezelés Függő jóváhagyások kártyája felsorolja a várakozó fiókokat, mindegyiknél Fiók aktiválása és elutasítás művelettel. Az elutasítás törlést jelent; nincs külön felfüggesztett állapot.
  • A bejelentkezett rendszergazdák értesítést kapnak az alkalmazásban: jelvény jelenik meg a Felhasználók bejegyzésnél, új regisztrációnál pedig felugró értesítés látható. A függő jóváhagyások összesítése körülbelül percenként lekérdeződik (GET /api/users/pending-approvals, csak rendszergazdák).
  • A jóváhagyás (PATCH /api/users/:id/approve, csak rendszergazdák) rögzíti, hogy melyik rendszergazda és mikor hagyta jóvá a fiókot. A szerepkört nem módosítja: a jóváhagyott fiókok user szerepkörűek maradnak, amíg egy rendszergazda elő nem lépteti őket. A jóváhagyás a felhasználó következő bejelentkezési kísérleténél lép életbe; semmit nem kell újra létrehozni.

A frissítés nem érinti a meglévő fiókokat: csak a funkció kiadása után nyilvánosan regisztrált fiókok indulnak függő állapotban. A Felhasználókezelésben rendszergazda által létrehozott fiókok azonnal aktívak.

Nyilvános regisztráció szándékos engedélyezése​

A regisztráció alapértelmezés szerint le van tiltva. Az alábbi backend környezeti változót csak addig állítsa be, amíg új helyi vagy OAuth-fiókokat kell elfogadni:

ENABLE_SIGNUP=true

A tervezett regisztrációs időszak után állítsa vissza false értékre. A meglévő helyi és OAuth-felhasználók továbbra is bejelentkezhetnek, a rendszergazdák pedig zárt nyilvános regisztráció mellett is létrehozhatnak fiókokat a Felhasználókezelésből.

Az üres adatbázis mindig engedélyez egy helyi rendszergazdát, még ENABLE_SIGNUP=false mellett is; az OAuth nem foglalhatja el ezt a kezdeti helyet. Privát távoli telepítésnél az alkalmazás indítása előtt helyezze a gazdagépnevet identitási engedélyezési lista, például Cloudflare Access mögé, majd a védett útvonalon hozza létre a kezdeti rendszergazdát.

Szerepkörök​

SzerepkörCél
adminPéldányadminisztráció, felhasználókezelés, rendszerbeállítások és megbízható Work-runtime-kezelés
userNormál csevegési, modell-, perszóna-, dokumentum- és beállítási munkafolyamatok

A modellek telepítése, törlése, másolása, feltöltése és kirakodása rendszergazdákra korlátozott, mert ezek a műveletek módosítják a gazdagép erőforrásait.

Work-hozzáférés​

A Work alapértelmezés szerint rendszergazdákra korlátozott, mert lehetővé teszi a kiválasztott modellnek tetszőleges parancsok végrehajtását kezelt konténerben. A rendszergazda a Beállítások Felhasználókezelés lapján minden aktív felhasználó számára megnyithatja a Worköt; a beállítás újraindítás után is megmarad, és azonnal érvénybe lép, a nyitott terminálmunkamenetekre is. A gazdagép-mappás munkaterületek minden módban csak rendszergazdák számára érhetők el, mert szerverútvonalakat csatolnak. A Work-hozzáféréssel rendelkezőket megbízható runtime-kezelőként, ne csupán WebUI-felhasználóként kezelje.

A rendszergazdai engedélyezés az adatbázis aktuális szerepkörét ellenőrzi, nem csupán a meglévő JWT-ben gyorsítótárazott szerepet. A rendszergazda visszaminősítése ezért azonnal visszavonja a Work-hozzáférést. Ezután a backend megpróbálja megszakítani az aktív futásokat, és leállítani a felhasználó Work-konténereit és előnézeteit, miközben megőrzi a feladatrekordokat és az elnevezett köteteket. Ha a Docker-tisztítás sikertelen, a hozzáférés visszavonva marad, a szerepkörmódosítás jelzi a tisztítási hibát, a kezelőnek pedig helyre kell állítania a Docker-hozzáférést és újra kell próbálnia a tisztítást.

A felhasználó törlése megsemmisíti a felhasználó Work-adatait. A Libre WebUI először leállítja a kezelt konténereket és eltávolítja a Work-köteteket, majd törli a fiókot és az adatbázisrekordokat. Ha a Docker nem tudja igazolni a sikeres tisztítást, a fióktörlés meghiúsul, hogy a rendszergazda kijavíthassa a runtime problémáját és újrapróbálhassa.

Csoportok és erőforrás-jogosultságok​

A rendszergazdák csoportokat hozhatnak létre és tagságokat kezelhetnek a Beállítások Felhasználókezelés lapján. A csoportok erőforrás-jogosultsági alanyok: egy csevegés, jegyzet, dokumentum, tudásgyűjtemény, mappa, perszóna, prompt, készség vagy naptár tulajdonosa az access API-n keresztül read, write vagy admin hozzáférést adhat felhasználónak vagy csoportnak — minden megosztható felület ugyanazt a megosztási párbeszédablakot használja (lásd: Megosztás) —, a rendszergazdák pedig ugyanígy korlátozhatják a regisztrált eszközszervereket felhasználókra vagy csoportokra. Az erőforrások alapértelmezés szerint privátak maradnak — a globális admin szerepkör nem ad hozzáférést más felhasználók tartalmához. A tagság a kérés idején értékelődik ki, így egy tag eltávolítása azonnal visszavonja a csoporton keresztül kapott hozzáférést. A Beállítások Felhasználókezelés lapjának „tényleges hozzáférés” nézete a „miért fér hozzá ez a felhasználó?” kérdésre a szerepkör, a csoportok, a funkcióhozzáférés és az összes rá vonatkozó jogosultság felsorolásával válaszol.

Biztonsági auditnapló​

A biztonságérzékeny műveletek — bejelentkezések és hibák, kijelentkezések, munkamenet- és tokenvisszavonások, felhasználó-, csoport-, jogosultság- és tokenmódosítások — csak hozzáfűzhető auditnaplóban rögzítődnek, a használati elemzésektől elkülönítve. A részletek tárolás előtt kitakarásra kerülnek: a titkosnak tűnő kulcsok kimaradnak, az adattartalom mérete korlátozott, így jelszavak, tokenek és prompttartalom soha nem kerül a naplóba. A csoport- és jogosultságmódosítások ugyanabban az adatbázis-tranzakcióban írják az auditeseményt, így módosítás nem létezhet nyom nélkül. A rendszergazdák a Beállítások Felhasználókezelés lapján kérdezhetik le a naplót; az alapértelmezett megőrzés 180 nap (AUDIT_RETENTION_DAYS).

Munkamenetek​

A backend a JWT_SECRET segítségével írja alá a JWT-ket. Éles környezetben állítson be stabil titkos értéket:

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

A JWT_SECRET módosítása érvényteleníti a meglévő munkameneteket. A helyi és OAuth-bejelentkezési tokenek a JWT_EXPIRES_IN értéket használják, amely alapértelmezés szerint 7d; módosítása az új munkameneteket érinti. A WebSocket-kapcsolatok a tartós tokent rövid élettartamú, egyszer használatos jegyre cserélik, és az alapul szolgáló munkamenet lejártakor bezáródnak.

Minden bejelentkezés szerveroldali munkamenetrekordot is létrehoz, amely a JWT-hez kötődik. A Beállítások → Munkamenetek minden eszközt felsorol a bejelentkezési móddal, az első és utolsó aktivitással, valamint a lejárattal. Egy munkamenet visszavonása (vagy a „Kijelentkezés a többi munkamenetből”) azonnal érvényteleníti a tokent minden replikán, és bezárja az aktív WebSocket-kapcsolatokat; a kijelentkezés ugyanígy visszavonja az aktuális munkamenetet. A funkció előtt kiadott tokenek nem tartalmaznak munkamenet-ID-t, és lejáratig érvényesek maradnak, kivéve ha egy új bejelentkezésből végzett „kijelentkezés a többi munkamenetből” fiókonkénti határidőt is beállít, amely elutasítja őket.

Kétfaktoros hitelesítés és passkeyek​

A Beállítások → Munkamenetek kezeli a második faktorokat és a jelszó nélküli bejelentkezést:

  • Hitelesítő alkalmazás (TOTP). A regisztráció base32 titkot és otpauth:// hivatkozást jelenít meg bármely hitelesítő alkalmazáshoz; az első hatjegyű kód megerősítése aktiválja, és tíz egyszer használatos helyreállítási kódot mutat. Ezután a jelszavas bejelentkezés munkamenet helyett rövid élettartamú kihívást ad vissza, a POST /api/auth/mfa/verify pedig TOTP- vagy helyreállítási kóddal fejezi be a bejelentkezést. Minden elfogadott kód időlépése rögzítődik, így az elfogott kód nem játszható vissza; a helyreállítási kódok csak kulcsolt, egyirányú keresési tokenként tárolódnak, és mindegyik pontosan egyszer működik. A helyreállítási kódok letiltásához vagy újragenerálásához újra igazolni kell egy faktort.
  • Passkeyek (WebAuthn). A „Bejelentkezés passkeyjel” jelszó nélküli bejelentkezést végez felderíthető hitelesítő adattal; a felhasználó ellenőrzése (képernyőzár, biometria vagy PIN) a regisztrációnál és bejelentkezésnél is szükséges. Az attesztáció none értékkel elfogadott, az ES256 és EdDSA hitelesítő adatok támogatottak, a hitelesítő anyag nyugalmi állapotban titkosított, az ID pedig kulcsolt keresési tokenként marad meg. A kihívások egyszer használatosak és öt perc után lejárnak; a nem nulla, de nem növekvő aláírásszámláló klónozási jelként elutasításra kerül. A passkeyek biztonságos (HTTPS) eredetet, fejlesztésnél pedig localhost címet igényelnek; több gazdagépnéven elérhető példánynál állítsa be a WEBAUTHN_RP_ID értékét.

A helyes jelszó után kiadott MFA-kihívástoken a JWT_SECRET értékből származtatott, de attól különböző titokkal van aláírva: soha nem hitelesíthet API-kérést, egy fiókhoz és egy célhoz kötődik, siker esetén pedig felhasználódik.

A rendszergazdák minden fióknál megkövetelhetik a második faktort (Felhasználók → kétfaktoros szabályzatkártya, vagy rögzítés MFA_REQUIRED_MODE=required értékkel). A második faktorral nem rendelkező felhasználókat a következő bejelentkezésnél, a munkamenet kiadása előtt végigvezeti a regisztráció. A rendszergazdák fiókhelyreállításhoz a felhasználólistából visszaállíthatják a felhasználó TOTP-regisztrációját; a passkeyek megmaradnak, mert azokat a felhasználó kezeli a beállításokban. A regisztráció, aktiválás, ellenőrzési hibák, letiltás, szabályzatmódosítások, passkey-regisztráció/-eltávolítás és rendszergazdai visszaállítások mind bekerülnek a biztonsági auditnaplóba.

Az MFA a jelszavas bejelentkezésekre vonatkozik. Az OAuth- és OIDC-bejelentkezések az identitásszolgáltató saját második faktorára támaszkodnak, és nem kapnak újabb kihívást. Az API-tokeneket ez nem érinti: soha nem használják a munkamenet-hitelesítést.

API-tokenek​

A Beállítások → API-kulcsok személyes hozzáférési tokeneket (előtag: lwk_) hoz létre programozott használathoz. A titok egyszer jelenik meg, és csak hashként tárolódik. Minden token kifejezett hatókörlistát tartalmaz (chat, models, documents, notes, personas, media, work, admin); a backend minden útvonalcsaládot szükséges hatókörhöz rendel, így a csak jegyzetekhez tartozó token nem fér hozzá a csevegésekhez vagy adminisztrációhoz, a munkamenetkezelés pedig tokennel soha nem érhető el. A tokenek opcionális lejáratot támogatnak, nyomon követik az utolsó használatot, bármikor visszavonhatók, és replikák között tokenenként sebességkorlátozottak. Adminhatókörű tokent csak rendszergazdák hozhatnak létre, és használatkor továbbra is szükséges a fiók admin szerepköre. A chat hatókörű token az OpenAI-kompatibilis nyilvános /v1 API kulcsa is.

Cloudflare Turnstile​

A Turnstile akkor védi a jelszavas bejelentkezést és regisztrációt, ha mindkét kulcs be van állítva:

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

A frontend külön login és signup műveletet rendel. A backend a Cloudflare segítségével ellenőrzi a tokent, és elutasítja azt a választ, amelynek gazdagépneve vagy művelete nem egyezik a kéréssel. Ha a TURNSTILE_EXPECTED_HOSTNAME nincs kifejezetten beállítva, a BASE_URL adja a várt gazdagépnevet.

Ha bármelyik kulcs hiányzik, a Turnstile le van tiltva.

GitHub OAuth​

Beállítás:

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

A GitHub OAuth-folyamat gh_ előtagú felhasználónévvel hoz létre helyi felhasználókat, és alapértelmezés szerint user szerepkört ad nekik.

Hugging Face OAuth​

Beállítás:

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

A Hugging Face OAuth-folyamat hf_ előtagú felhasználónévvel hoz létre helyi felhasználókat, és alapértelmezés szerint user szerepkört ad nekik.

Mindkét OAuth-szolgáltató kriptográfiailag véletlen state értéket használ, amely rövid élettartamú HttpOnly, SameSite cookie-hoz kötődik. A callback elutasítja a hiányzó vagy nem egyező state értéket. Sikeres callback után a JWT egy 60 másodperces HttpOnly cookie-ban jut vissza a frontendhez, amely azonnal kicserélődik és törlődik; bearer tokenek soha nem kerülnek callback URL-ekbe, böngészőelőzményekbe vagy referrer fejlécekbe.

Átirányítások és CORS​

Állítsa be a BASE_URL értékét a callback alapértékeihez, a CORS_ORIGIN értékét pedig a böngészőhozzáféréshez:

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

Helyi fejlesztéshez adja meg a Vite fejlesztési eredetét:

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

Bemutató mód​

A bemutató mód frontend-előnézeti mód. Előre kitölti a letiltott bemutató hitelesítő adatokat, és szimulált API-válaszokat használ. Nem éles hitelesítési mód.

Biztonsági ellenőrzőlista​

  • Állítson be erős JWT_SECRET értéket.
  • A DATA_DIR könyvtárat tartós, hozzáférés-vezérelt tárolón tartsa.
  • Az ENCRYPTION_KEY értékéről az adatbázissal együtt készítsen biztonsági mentést.
  • Nyilvános regisztrációhoz állítsa be a Turnstile-t.
  • Nyilvános telepítéseknél használjon HTTPS-t.
  • A szolgáltatói API-kulcsokat a szükséges legkisebb hatókörre korlátozza.
  • Az OAuth callback URL-eket pontosan tartsa.
  • Work-hozzáférést (rendszergazdai fiókok vagy minden felhasználónak nyitott mód) csak a backend konténer-runtime-jának kezelésére megbízhatónak tekintett személyeknek adjon.

Kapcsolódó dokumentáció​