Přeskočit na hlavní obsah

Ověřování a zabezpečení

Libre WebUI používá místní uživatelské účty s relacemi JWT. Nová instalace vždy umožní vytvořit jednoho místního správce. Veřejná registrace dalších místních a OAuth účtů je ve výchozím stavu zavřená.

První nastavení​

Když databáze nemá uživatele:

  1. Libre WebUI zobrazí první nastavení.
  2. Uživatel vytvoří první místní účet.
  3. Účet získá roli admin.
  4. Každá další veřejná registrace zůstává zavřená, pokud ji výslovně nezapnete.

Existující databáze zachovají aktuální uživatele a role.

Místní účty​

Místní registrace vyžaduje:

  • Uživatelské jméno
  • Heslo mezi 12 znaky a 72 bajty UTF-8 s velkým a malým písmenem a číslicí
  • Volitelný e-mail

Hesla se před uložením hashují pomocí bcrypt. Trasy přihlášení a registrace mají omezenou rychlost.

Schválení registrace​

Veřejná registrace sama neposkytuje přístup. Každý účet vytvořený formulářem nebo poskytovatelem OAuth začíná ve stavu pending a před přihlášením jej musí schválit správce.

Výjimkou je první účet: v prázdné databázi se atomicky vytvoří jako active s rolí admin, aby nová instalace měla funkčního správce. Všechny další registrace čekají na kontrolu.

Co vidí čekající uživatel:

  • Registrace uspěje, ale nevrátí token relace. API odpoví 202 s approvalRequired: true a UI vysvětlí, že účet musí schválit správce.
  • Přihlášení správným heslem se odmítne kódem 403 a ACCOUNT_PENDING („Účet čeká na schválení správcem“). OAuth přesměruje na přihlašovací stránku s ?approval=pending.
  • Stav účtu se při každém ověřeném požadavku znovu čte z databáze, takže relace nemůže přežít stav active účtu.

Co vidí správce:

  • Správa uživatelů ukazuje kartu Čekající schválení s účty, akcí Aktivovat účet a odmítnutím. Odmítnutí znamená smazání; samostatný pozastavený stav neexistuje.
  • Přihlášení správci dostávají upozornění v aplikaci, odznak u Uživatelů a oznámení při nové registraci. Souhrn se dotazuje asi jednou za minutu (GET /api/users/pending-approvals, jen správci).
  • Schválení (PATCH /api/users/:id/approve, jen správci) zaznamená kdo a kdy účet schválil. Roli nemění: účet zůstává user, dokud jej správce nepovýší. Schválení platí při příštím přihlášení; nic se nemusí vytvářet znovu.

Existující účty aktualizace neovlivní. Jako čekající začínají pouze účty vytvořené veřejnou registrací po zavedení funkce. Účty vytvořené správcem jsou aktivní ihned.

Záměrné zapnutí veřejné registrace​

Registrace je ve výchozím stavu vypnutá. Proměnnou backendu níže nastavte pouze po dobu, kdy se mají přijímat nové účty:

ENABLE_SIGNUP=true

Po plánovaném okně ji vraťte na false. Existující uživatelé se mohou stále přihlašovat a správci vytvářet účty i při zavřené registraci.

Prázdná databáze vždy dovolí jednoho místního správce i při ENABLE_SIGNUP=false; OAuth tuto pozici nemůže obsadit. U soukromého vzdáleného nasazení umístěte hostitele za seznam povolených identit, například Cloudflare Access, a prvního správce vytvořte chráněnou trasou.

Role​

RoleÚčel
adminSpráva instance, uživatelů, systému a důvěryhodný provoz runtime Work
userBěžné toky chatu, modelu, persony, dokumentů a nastavení

Instalace, mazání, kopírování, push a uvolnění modelů jsou omezené na správce, protože mění prostředky hostitele.

Přístup Work​

Work je ve výchozím stavu omezený na správce, protože umožňuje modelu spouštět libovolné příkazy ve spravovaném kontejneru. Správce jej může otevřít všem aktivním uživatelům; nastavení přetrvá restart a platí ihned i pro otevřené terminály. Pracovní prostory se složkou hostitele zůstávají jen pro správce, protože bind-mountují serverové cesty. Každého s přístupem Work považujte za důvěryhodného operátora runtime, ne jen uživatele WebUI.

Oprávnění správce se kontroluje proti aktuální roli v databázi, ne jen cache JWT. Snížení role proto okamžitě odvolá Work. Backend se pokusí ukončit aktivní běhy a kontejnery i náhledy, přičemž zachová záznamy a pojmenované svazky. Pokud čištění Docker selže, přístup zůstává odvolaný, změna role chybu ohlásí a operátor musí obnovit přístup a opakovat čištění.

Smazání uživatele zničí jeho data Work. Libre WebUI nejprve zastaví kontejnery a odstraní svazky, poté účet a záznamy. Pokud Docker nedokáže potvrdit úspěšné vyčištění, smazání selže, aby správce mohl runtime opravit a opakovat.

Skupiny a oprávnění prostředků​

Správci vytvářejí skupiny a spravují členství. Skupiny jsou subjekty oprávnění: vlastník chatu, poznámky, dokumentu, kolekce, složky, persony, promptu, dovednosti nebo kalendáře může přes API udělit read, write či admin uživateli nebo skupině. Všechny sdílené plochy používají stejný dialog (viz Sdílení) a servery nástrojů lze omezit stejně. Prostředky zůstávají soukromé; globální admin neposkytuje přístup k cizímu obsahu. Členství se vyhodnocuje při požadavku, takže odebrání člena odvolá přístup ihned. Zobrazení „efektivní přístup“ vysvětluje oprávnění výpisem role, skupin, funkcí a grantů.

Bezpečnostní auditní protokol​

Citlivé akce—úspěšná i neúspěšná přihlášení, odhlášení, odvolání relací a tokenů a změny uživatelů, skupin, oprávnění a tokenů—se zaznamenávají do odděleného protokolu pouze pro přidávání. Podrobnosti se před uložením maskují: tajné klíče se zahodí a payload se omezí, takže hesla, tokeny ani prompty do protokolu nevstoupí. Změny skupin a oprávnění zapisují auditní událost ve stejné transakci. Výchozí uchování je 180 dní (AUDIT_RETENTION_DAYS).

Relace​

Backend podepisuje JWT pomocí JWT_SECRET. Pro produkci nastavte stabilní tajný údaj:

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

Změna JWT_SECRET zneplatní existující relace. Místní a OAuth tokeny používají JWT_EXPIRES_IN, výchozí 7d; změna ovlivní nové relace. WebSocket vymění trvalý token za krátkodobý jednorázový lístek a zavře se po vypršení relace.

Každé přihlášení vytvoří serverový záznam relace svázaný s JWT. Nastavení → Relace vypíše zařízení, metodu, první a poslední aktivitu a vypršení. Odvolání nebo Odhlásit ostatní relace okamžitě zneplatní token na všech replikách a zavře WebSocket. Starší tokeny bez ID platí do vypršení, ale tato akce z nového přihlášení také nastaví hranici účtu, která je odmítne.

Dvoufaktorové ověřování a passkeys​

Nastavení → Relace spravuje druhé faktory i přihlášení bez hesla:

  • Ověřovací aplikace (TOTP). Registrace ukáže tajemství base32 a odkaz otpauth:// pro libovolnou aplikaci. První šestimístný kód funkci aktivuje a zobrazí deset jednorázových obnovovacích kódů. Poté přihlášení heslem vrátí krátkodobou výzvu místo relace a POST /api/auth/mfa/verify přihlášení dokončí kódem TOTP nebo obnovy. Časový krok přijatého kódu se zaznamená, aby nešel přehrát. Obnovovací kódy se ukládají jen jako jednosměrné tokeny s klíčem a každý funguje jednou. Vypnutí nebo nové kódy vyžadují opětovné prokázání faktoru.
  • Passkeys (WebAuthn). Přihlásit se pomocí passkey provede přihlášení bez hesla rozpoznatelným údajem. Ověření uživatele zámkem obrazovky, biometrií nebo PIN je povinné. Attestation se přijímá jako none, podporuje se ES256 a EdDSA a údaje jsou při uložení šifrované s ID jako vyhledávací token s klíčem. Výzvy jsou jednorázové a vyprší za pět minut; čítač podpisu, který se nezvýší, se odmítne jako signál klonu. Passkeys vyžadují bezpečný HTTPS origin nebo localhost. Při více hostitelích nastavte WEBAUTHN_RP_ID.

Token výzvy MFA po správném hesle je podepsaný tajemstvím odvozeným od JWT_SECRET, ale odlišným. Nemůže ověřit požadavek API, váže se na účet a účel a po úspěchu se spotřebuje.

Správci mohou vyžadovat druhý faktor pro všechny účty (Uživatelé → karta dvoufaktorové zásady nebo MFA_REQUIRED_MODE=required). Uživatel bez faktoru projde registrací při příštím přihlášení před vydáním relace. Správce může resetovat TOTP pro obnovu účtu; passkeys zůstávají, protože je spravuje uživatel. Registrace, aktivace, chyby, vypnutí, změny zásad, přidání/odebrání passkey a resety správce se auditují.

MFA platí pro přihlášení heslem. OAuth a OIDC spoléhají na druhý faktor poskytovatele identity a znovu se nevyzývají. Tokeny API nejsou ovlivněné, protože nepoužívají ověření relace.

Tokeny API​

Nastavení → Klíče API vytváří osobní přístupové tokeny s prefixem lwk_. Tajemství se zobrazí jednou a uloží jen jako hash. Každý token má výslovný seznam rozsahů (chat, models, documents, notes, personas, media, work, admin); backend mapuje rodiny tras na rozsah, takže token poznámek nedosáhne na chat ani správu a správa relací není tokenem dostupná. Tokeny podporují volitelné vypršení, sledují poslední použití, lze je odvolat a mají omezenou rychlost napříč replikami. Admin token vytváří jen správce a při použití stále vyžaduje admin roli. Token s chat je i klíčem k veřejnému API /v1 kompatibilnímu s OpenAI.

Cloudflare Turnstile​

Turnstile chrání přihlášení a registraci heslem při konfiguraci obou klíčů:

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

Frontend přiřadí oddělené akce login a signup. Backend ověří token u Cloudflare a odmítne odpověď s neodpovídajícím hostitelem nebo akcí. BASE_URL poskytne očekávaný hostitel, pokud není nastaven TURNSTILE_EXPECTED_HOSTNAME.

Pokud některý klíč chybí, Turnstile je vypnutý.

GitHub OAuth​

Konfigurace:

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

GitHub OAuth vytváří místní uživatele s prefixem gh_ a výchozí rolí user.

Hugging Face OAuth​

Configure:

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

Hugging Face OAuth vytváří místní uživatele s prefixem hf_ a výchozí rolí user.

Oba poskytovatelé používají kryptograficky náhodný state svázaný s krátkodobou cookie HttpOnly, SameSite. Callback odmítne chybějící nebo neshodný stav. Po úspěchu se JWT vrátí ve 60sekundové cookie HttpOnly, která se ihned vymění a smaže; bearer tokeny se nikdy nevkládají do URL, historie ani headerů referrer.

Redirects and CORS​

Nastavte BASE_URL pro výchozí callback a CORS_ORIGIN pro přístup prohlížeče:

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

Při místním vývoji zahrňte vývojový origin Vite:

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

Ukázkový režim​

Ukázkový režim je náhledový režim frontendu. Předvyplní zakázané ukázkové údaje a používá simulované odpovědi API. Nejde o produkční ověřování.

Security Checklist​

  • Nastavte silný JWT_SECRET.
  • Uchovávejte DATA_DIR v trvalém úložišti s řízeným přístupem.
  • Zálohujte ENCRYPTION_KEY s databází.
  • Nakonfigurujte Turnstile pro veřejnou registraci.
  • Pro veřejné nasazení používejte HTTPS.
  • Omezte klíče poskytovatelů na minimální rozsah.
  • Udržujte URL callback OAuth přesné.
  • Přístup Work poskytujte pouze osobám důvěryhodným pro provoz runtime kontejnerů backendu.

Související dokumentace​