Zum Hauptinhalt springen

Authentifizierung und Sicherheit

Libre WebUI verwendet lokale Konten mit JWT-Sitzungen. Eine neue Installation erlaubt immer das Anlegen eines ersten lokalen Administrators. Die öffentliche Registrierung aller weiteren lokalen oder OAuth-Konten ist standardmäßig geschlossen.

Ersteinrichtung​

Wenn die Datenbank keine Benutzer enthält:

  1. Libre WebUI zeigt den Einrichtungsablauf.
  2. Der Benutzer erstellt das erste lokale Konto.
  3. Das Konto erhält die Rolle admin.
  4. Jede weitere öffentliche Registrierung bleibt geschlossen, sofern sie nicht ausdrücklich aktiviert wird.

Bestehende Datenbanken behalten ihre Benutzer und Rollen.

Lokale Konten​

Die lokale Registrierung erfordert:

  • Benutzername
  • Passwort mit 12 Zeichen bis 72 UTF-8-Byte, Groß- und Kleinbuchstaben sowie Zahl
  • Optionale E-Mail-Adresse

Passwörter werden vor der Speicherung mit bcrypt gehasht. Anmeldung und Registrierung sind ratenbegrenzt.

Genehmigung von Registrierungen​

Eine öffentliche Registrierung gewährt nicht automatisch Zugriff. Jedes über Formular oder OAuth erstellte Konto beginnt im Zustand pending und muss vor der Anmeldung von einem Administrator genehmigt werden.

Nur der Start ist ausgenommen: Das erste echte Konto einer leeren Datenbank wird atomar als active mit Rolle admin erstellt, sodass eine neue Installation einen funktionierenden Administrator erhält. Alle weiteren warten auf Prüfung.

Ein wartender Benutzer sieht:

  • Die Registrierung gelingt, liefert aber kein Sitzungstoken. Die API antwortet mit 202 und approvalRequired: true; die Oberfläche erklärt die erforderliche Genehmigung.
  • Eine korrekte Passwortanmeldung wird mit 403 und ACCOUNT_PENDING ("Your account is waiting for administrator approval") abgewiesen. OAuth leitet mit ?approval=pending zur Anmeldung zurück.
  • Der Kontozustand wird bei jeder authentifizierten Anfrage neu gelesen, sodass keine Sitzung den Zustand active überdauert.

Ein Administrator sieht:

  • Die Benutzerverwaltung zeigt Ausstehende Genehmigungen mit Konto aktivieren und Ablehnung. Ablehnen löscht; es gibt keinen eigenen gesperrten Zustand.
  • Angemeldete Administratoren erhalten ein Abzeichen bei Benutzer und einen Hinweis bei neuen Registrierungen. Die Zusammenfassung wird etwa minütlich abgefragt (GET /api/users/pending-approvals, nur Administratoren).
  • Die Genehmigung (PATCH /api/users/:id/approve, nur Administratoren) protokolliert wer und wann. Sie ändert die Rolle nicht; genehmigte Konten bleiben user, bis sie hochgestuft werden. Sie gilt beim nächsten Anmeldeversuch; nichts muss neu erstellt werden.

Bestehende Konten sind von Upgrades nicht betroffen. Nur nach Einführung öffentlich erstellte Konten beginnen wartend. Vom Administrator erstellte Konten sind sofort aktiv.

Öffentliche Registrierung bewusst aktivieren​

Die Registrierung ist standardmäßig deaktiviert. Setze die Backendvariable nur während eines gewünschten Aufnahmefensters:

ENABLE_SIGNUP=true

Setze sie danach auf false. Bestehende Benutzer können sich weiter anmelden und Administratoren Konten erstellen.

Eine leere Datenbank erlaubt auch bei ENABLE_SIGNUP=false einen lokalen Administrator; OAuth kann diesen Platz nicht beanspruchen. Schütze bei einer privaten Remote-Bereitstellung den Host vor dem ersten Start durch eine Identitätsfreigabe wie Cloudflare Access und erstelle das Konto über den geschützten Weg.

Rollen​

RolleZweck
adminInstanz- und Benutzerverwaltung, Systemeinstellungen und vertrauenswürdiger Betrieb der Work-Laufzeit
userNormale Chat-, Modell-, Persona-, Dokument- und Einstellungsabläufe

Installation, Löschung, Kopieren, Push und Entladen von Modellen sind auf Administratoren beschränkt, da sie Hostressourcen ändern.

Work-Zugriff​

Work ist standardmäßig Administratoren vorbehalten, weil ein gewähltes Modell beliebige Befehle in einem verwalteten Container ausführen kann. Ein Administrator kann Work unter Einstellungen > Benutzerverwaltung für alle aktiven Benutzer öffnen; die Einstellung bleibt nach Neustarts erhalten und gilt sofort, auch für offene Terminals. Hostordner-Arbeitsbereiche bleiben stets Administratoren vorbehalten, da sie Serverpfade einbinden. Behandle alle mit Work-Zugriff als vertrauenswürdige Laufzeitbetreiber, nicht nur WebUI-Benutzer.

Die Autorisierung prüft die aktuelle Datenbankrolle, nicht nur die im JWT gespeicherte. Eine Herabstufung widerruft Work sofort. Das Backend versucht dann, aktive Ausführungen abzubrechen und Container und Vorschauen zu stoppen, während Aufgaben und Volumes erhalten bleiben. Scheitert Docker-Bereinigung, bleibt der Zugriff widerrufen, der Rollenwechsel meldet den Fehler und ein Betreiber muss Docker wiederherstellen und erneut bereinigen.

Das Löschen eines Benutzers zerstört dessen Work-Daten. Libre WebUI stoppt zuerst Container und entfernt Volumes, dann Konto und Datenbankeinträge. Kann Docker den Erfolg nicht bestätigen, schlägt die Löschung fehl, damit das Laufzeitproblem korrigiert werden kann.

Gruppen und Ressourcenfreigaben​

Administratoren erstellen Gruppen und verwalten Mitgliedschaften. Gruppen sind Prinzipale für Freigaben: Besitzer von Chat, Notiz, Dokument, Wissenssammlung, Ordner, Persona, Prompt, Skill oder Kalender können read, write oder admin über die Zugriffs-API an Benutzer oder Gruppen vergeben. Alle teilbaren Oberflächen verwenden denselben Dialog (siehe Freigabe); Werkzeugserver lassen sich ebenso einschränken. Ressourcen bleiben standardmäßig privat; die globale Rolle admin gibt keinen Zugriff auf fremde Inhalte. Mitgliedschaften werden bei jeder Anfrage bewertet, daher widerruft das Entfernen sofort. „Effektiver Zugriff“ unter Einstellungen > Benutzerverwaltung erklärt den Grund anhand von Rolle, Gruppen, Funktionszugriff und allen Freigaben.

Sicherheitsprüfprotokoll​

Sensible Aktionen – Anmeldungen und Fehler, Abmeldungen, Widerrufe sowie Benutzer-, Gruppen-, Freigabe- und Tokenänderungen – werden in einem reinen Anfügeprotokoll getrennt von Nutzungsanalysen erfasst. Details werden vor der Speicherung redigiert: geheimnisähnliche Schlüssel entfernt und Nutzlasten begrenzt, sodass Passwörter, Tokens und Prompts nie hineingelangen. Gruppen- und Freigabeänderungen schreiben das Ereignis in derselben Transaktion; keine Änderung existiert ohne Spur. Administratoren fragen es unter Einstellungen > Benutzerverwaltung ab; Standardaufbewahrung 180 Tage (AUDIT_RETENTION_DAYS).

Sitzungen​

Das Backend signiert JWTs mit JWT_SECRET. Setze in Produktion ein stabiles Geheimnis:

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

Ein Wechsel von JWT_SECRET entwertet bestehende Sitzungen. Lokale und OAuth-Tokens verwenden JWT_EXPIRES_IN, standardmäßig 7d; Änderungen gelten für neue Sitzungen. WebSockets tauschen das dauerhafte Token gegen ein kurzlebiges Einmalticket und schließen beim Sitzungsablauf.

Jede Anmeldung erzeugt außerdem einen serverseitigen Sitzungsdatensatz, der im JWT gebunden ist. Einstellungen → Sitzungen listet Geräte, Methode, erste/letzte Aktivität und Ablauf. Ein Widerruf dort oder „Andere Sitzungen abmelden“ entwertet das Token sofort auf allen Replikaten und schließt WebSockets; Abmelden widerruft die aktuelle Sitzung. Ältere Tokens ohne Sitzungs-ID gelten bis zum Ablauf, außer ein neuer Login setzt mit „Andere Sitzungen abmelden“ einen kontoweiten Stichtag.

Zwei-Faktor-Authentifizierung und Passkeys​

Einstellungen → Sitzungen verwaltet zweite Faktoren und passwortlose Anmeldung:

  • Authentifizierungs-App (TOTP). Die Einrichtung zeigt ein Base32-Geheimnis und einen otpauth://-Link; der erste 6-stellige Code aktiviert und zeigt zehn einmalige Wiederherstellungscodes. Danach liefert die Passwortanmeldung eine kurze Challenge, und POST /api/auth/mfa/verify schließt sie mit TOTP oder Wiederherstellung ab. Der Zeitschritt jedes akzeptierten Codes wird gespeichert, um Wiederholung abzufangen; Wiederherstellungscodes liegen nur als schlüsselgebundene Einweg-Suchwerte vor und funktionieren einmal. Deaktivieren oder Neugenerieren erfordert erneuten Faktornachweis.
  • Passkeys (WebAuthn). „Mit Passkey anmelden“ verwendet eine auffindbare Zugangsdaten ohne Passwort; Benutzerverifizierung (Bildschirmsperre, Biometrie oder PIN) ist bei Registrierung und Anmeldung Pflicht. Attestierung none wird akzeptiert, ES256 und EdDSA unterstützt und das Material verschlüsselt gespeichert, während die ID als schlüsselgebundener Suchwert bleibt. Challenges sind einmalig und laufen nach fünf Minuten ab; ein nichtnull Signaturzähler ohne Fortschritt wird als Klonhinweis abgewiesen. Passkeys benötigen sicheren HTTPS-Ursprung oder localhost; setze WEBAUTHN_RP_ID bei mehreren Hostnamen.

Das MFA-Challengetoken wird mit einem von JWT_SECRET abgeleiteten, aber getrennten Geheimnis signiert: Es authentifiziert niemals eine API, ist an Konto und Zweck gebunden und wird bei Erfolg verbraucht.

Administratoren können einen zweiten Faktor für alle verlangen (Benutzer → Richtlinienkarte oder MFA_REQUIRED_MODE=required). Benutzer ohne Faktor werden beim nächsten Login vor Sitzungsübergabe durch die Einrichtung geführt. Administratoren können TOTP zur Kontowiederherstellung zurücksetzen; Passkeys bleiben, da Benutzer sie verwalten. Einrichtung, Aktivierung, Fehler, Deaktivierung, Richtlinienänderungen, Passkey-Verwaltung und Rücksetzungen werden protokolliert.

MFA gilt für Passwortanmeldungen. OAuth und OIDC vertrauen dem zweiten Faktor des Identitätsanbieters und fordern nicht erneut. API-Tokens sind nicht betroffen.

API-Tokens​

Einstellungen → API-Schlüssel erstellt persönliche Tokens (Präfix lwk_) zur programmatischen Nutzung. Das Geheimnis wird einmal angezeigt und nur als Hash gespeichert. Jedes Token hat explizite Bereiche (chat, models, documents, notes, personas, media, work, admin); das Backend ordnet Routenfamilien zu, sodass ein Notes-Token weder Chats noch Verwaltung erreicht und Sitzungsverwaltung nie mit Token zugänglich ist. Tokens können ablaufen, erfassen letzte Nutzung, sind widerrufbar und replikaübergreifend pro Token begrenzt. admin-Tokens können nur Administratoren erstellen und das Konto muss beim Einsatz Administrator bleiben. Ein chat-Token ist auch Schlüssel der OpenAI-kompatiblen öffentlichen /v1-API.

Cloudflare Turnstile​

Turnstile schützt Passwortanmeldung und Registrierung, wenn beide Schlüssel gesetzt sind:

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

Das Frontend verwendet getrennte Aktionen login und signup. Das Backend prüft das Token bei Cloudflare und lehnt falschen Host oder Aktion ab. BASE_URL liefert den erwarteten Host, wenn TURNSTILE_EXPECTED_HOSTNAME fehlt.

Fehlt ein Schlüssel, ist Turnstile deaktiviert.

GitHub OAuth​

Konfiguriere:

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

Der Ablauf erstellt lokale Benutzer mit Präfix gh_ und Standardrolle user.

Hugging Face OAuth​

Konfiguriere:

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

Der Ablauf erstellt lokale Benutzer mit Präfix hf_ und Standardrolle user.

Beide Anbieter verwenden einen kryptografisch zufälligen state, gebunden an ein kurzlebiges HttpOnly-SameSite-Cookie. Der Callback verwirft fehlende oder falsche Zustände. Nach Erfolg gelangt das JWT in einem 60-sekündigen HttpOnly-Cookie zum Frontend, wird sofort getauscht und gelöscht; Bearer-Tokens stehen nie in Callback-URLs, Browserverlauf oder Referer-Kopfzeilen.

Weiterleitungen und CORS​

Setze BASE_URL für Callback-Vorgaben und CORS_ORIGIN für Browserzugriff:

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

Füge lokal den Vite-Ursprung hinzu:

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

Demomodus​

Der Demomodus ist eine Frontendvorschau mit vorausgefüllten deaktivierten Zugangsdaten und simulierten API-Antworten. Er ist keine Produktionsauthentifizierung.

Sicherheitscheckliste​

  • Setze ein starkes JWT_SECRET.
  • Bewahre DATA_DIR persistent und zugriffsgeschützt auf.
  • Sichere ENCRYPTION_KEY mit der Datenbank.
  • Konfiguriere Turnstile für öffentliche Registrierung.
  • Nutze HTTPS für öffentliche Bereitstellungen.
  • Begrenze Anbieterschlüssel auf den nötigen Bereich.
  • Halte OAuth-Callback-URLs exakt.
  • Gewähre Work nur Personen, denen du den Betrieb der Containerlaufzeit anvertraust.

Verwandte Dokumentation​