Granulare Zugriffskontrolle

LibreChat wird mit einem vollständigen Autorisierungssystem zusätzlich zur Authentifizierung ausgeliefert. Der Zugriff ist kein „Alles-oder-Nichts“-Prinzip: Jede teilbare Entität in der App (Agents, Prompts, MCP Server, Remote Agents, Dateien, Konversationen) verfügt über eine eigene Zugriffssteuerungsliste (Access Control List, ACL), und jede Funktion kann unabhängig pro Benutzer, Gruppe, Rolle oder öffentlich aktiviert oder eingeschränkt werden.

Diese Seite erklärt, wie die einzelnen Komponenten zusammenwirken, damit Sie Berechtigungen passend für Ihre Organisation modellieren können – von einem kleinen Team, in dem jeder alles frei teilen kann, bis hin zu einer Unternehmensbereitstellung mit synchronisierten Entra ID-Gruppen, benutzerdefinierten Rollen und delegierten Administratoren.

Das Zugriffsmodell auf einen Blick

Die Autorisierung von LibreChat besteht aus drei unabhängigen Ebenen, die zusammenwirken:

Alle drei werden für dieselben vier Haupttypen ausgewertet:

• Benutzer: ein individuelles LibreChat-Konto
• Gruppe: eine Sammlung von Benutzern (lokal oder synchronisiert aus Entra ID)
• Rolle: ein benanntes Berechtigungsprofil (z. B. USER, ADMIN oder eine beliebige benutzerdefinierte Rolle)
• Öffentlich: jeder authentifizierte Benutzer auf der Instanz

Ebene 1: Funktionsberechtigungen (Rollenbasiert)

Berechtigungen auf Funktionsebene beschränken ganze Fähigkeiten der App für eine bestimmte Rolle. Sie beantworten Fragen wie "Können Benutzer in dieser Rolle überhaupt Agents erstellen?", "Dürfen sie Prompts öffentlich teilen?", "Können sie den Code-Interpreter aufrufen?".

Integrierte Systemrollen

LibreChat wird mit zwei Systemrollen ausgeliefert, die immer vorhanden sind und nicht gelöscht werden können:

• ADMIN: wird dem ersten Konto zugewiesen, das auf der Instanz registriert wurde. Admins können alle Ressourcen einsehen, jede Einstellung ändern, auf das Admin-Panel zugreifen und das plattformweite Verhalten konfigurieren.
• USER: die Standardrolle, die jedem neuen Konto zugewiesen wird.

Admins können manuell befördert werden, indem das Benutzerdokument in MongoDB aktualisiert wird, siehe Administrator Controls.

Berechtigungstypen

Jede Rolle enthält eine Matrix aus Berechtigungstypen × Aktionen:

Die Unterscheidung zwischen SHARE und SHARE_PUBLIC ist wichtig: Sie können einer Rolle erlauben, Agents mit bestimmten Benutzern oder Gruppen zu teilen (SHARE), ohne dass diese die Agents für jeden auf der Instanz sichtbar machen können (SHARE_PUBLIC).

Konfigurieren von Funktionsberechtigungen

Die empfohlene Methode zur Verwaltung von Funktionsberechtigungen ist das LibreChat Admin Panel, welches die Berechtigungsmatrix direkt für jede Rolle (einschließlich aller von Ihnen erstellten benutzerdefinierten Rollen) bearbeitet. Änderungen werden ohne ein erneutes Deployment von LibreChat wirksam und beziehen sich genau auf die Rolle, die Sie ändern möchten, anstatt auf den globalen USER-Standard.

Benutzerdefinierte Rollen

Neben USER und ADMIN können Administratoren benutzerdefinierte Rollen mit ihrer eigenen Funktionsberechtigungsmatrix erstellen (eingeführt in v0.8.5; siehe #12528). Ein Benutzer kann mehrere Rollen innehaben, und seine effektiven Berechtigungen sind die Vereinigung aller zugewiesenen Rollen. Benutzerdefinierte Rollen werden über das Admin-Panel verwaltet.

Rollen- und gruppenspezifische Konfigurationsüberschreibungen

Zusätzlich zu Feature-Flags wurde mit v0.8.5 ein DB-basiertes Konfigurations-Override-System eingeführt (#12354). Dies ermöglicht es Ihnen, bestimmten Gruppen oder Rollen eine andere Konfiguration im librechat.yaml-Stil zuzuweisen. Zum Beispiel könnte eine "Research"-Gruppe Zugriff auf zusätzliche endpoints, ein höheres Rekursionslimit und andere Agenten-Funktionen als die Standardeinstellung haben. Overrides werden bei der Anmeldung aufgelöst und auf die Basiskonfiguration angewendet.

Ebene 2: Ressourcen-ACLs (Freigabe pro Entität)

Jede teilbare Ressource in LibreChat verfügt über eine eigene Zugriffssteuerungsliste (Access Control List), unabhängig von rollenbasierten Berechtigungen. Auf diese Weise entscheidet ein einzelner Benutzer mit SHARE-Berechtigung, wer Zugriff auf seinen Agenten, Prompt oder MCP Server erhält.

Ressourcentypen

Ressourcen-ACLs gelten derzeit für:

• Agents (agent)
• Prompts / Prompt-Gruppen (promptGroup)
• MCP-Server (mcpServer)
• Remote Agents (remoteAgent), für die Agents API
• Dateien (file), die normalerweise von der Ressource geerbt werden, die sie verwendet
• Projekte (project), unterstützen Vererbung, sodass Ressourcen, die für ein Projekt freigegeben wurden, automatisch ACLs erben

Zugriffsrollen (Berechtigungsvoreinstellungen)

Anstatt Endbenutzern rohe Berechtigungs-Bits offenzulegen, verwendet das Teilen drei benannte Rollen pro Ressourcentyp:

Unter der Haube werden Berechtigungen als Bitmaske (permBits) für jedes (Ressource, Principal)-Paar gespeichert; Obermengen werden automatisch gehandhabt, sodass die Gewährung von Editor-Rechten implizit auch Viewer-Rechte beinhaltet.

Zugriff über die UI gewähren

1. Öffnen Sie die Ressource (Agent Builder, Prompt-Formular, MCP-Server-Einstellungen usw.)
2. Klicken Sie auf die Schaltfläche Share (sichtbar, wenn Sie der Eigentümer oder ein Administrator sind oder Ihnen SHARE-Rechte gewährt wurden)
3. Im Dialog zum Teilen:
   • Verwenden Sie die Personenauswahl, um nach Benutzern, Gruppen oder Rollen zu suchen, die hinzugefügt werden sollen.
   • Wählen Sie eine Zugriffsrolle (Viewer / Editor / Owner) pro Principal
   • Optional können Sie den Öffentlichen Zugriff umschalten, um die Ressource für alle auf der Instanz sichtbar zu machen (erfordert die SHARE_PUBLIC Funktionsberechtigung).
4. Speichern. Berechtigte sehen die Ressource beim nächsten Aktualisieren.

Was Empfänger sehen

• Betrachter sehen die Ressource als ein sofort einsatzbereites Element in der entsprechenden Auswahl (z. B. im Agenten-Dropdown). Sie können den Builder nicht öffnen, die rohen Anweisungen nicht einsehen und die Einstellungen nicht ändern.
• Editoren können die Konfiguration der Ressource öffnen und bearbeiten, sie jedoch nicht löschen oder erneut freigeben.
• Besitzer haben die gleiche Benutzeroberfläche wie der ursprüngliche Autor und können Inhalte frei löschen und erneut teilen.
• Der ursprüngliche Autor behält immer die volle Kontrolle, unabhängig vom ACL-Status, und Administratoren können jede Ressource auf der Instanz verwalten.

Projektvererbung

Berechtigungen können von einem übergeordneten project geerbt werden. Wenn ein ACL-Eintrag vererbt wird, verweist der inheritedFrom-Link zurück auf die Quelle. Dies ist die Grundlage für das „Global“-Projekt in LibreChat, bei dem eine Ressource, die dem globalen Projekt hinzugefügt wurde, für alle Benutzer verfügbar wird, ohne dass ein Eintrag pro Principal erforderlich ist.

Ebene 3: System-Berechtigungen (Admin-Funktionen)

System-Berechtigungen sind eine separate Berechtigungstabelle, die für Funktionen auf Admin-Ebene verwendet wird und Fragen beantwortet wie "Kann dieser Benutzer auf das Admin-Panel zugreifen?" oder "Kann diese Gruppe MCP-Server global verwalten?". Sie sind immer an einen Principal (Benutzer, Gruppe oder Rolle) und eine Berechtigungszeichenfolge gebunden.

Die kanonischen Funktionen umfassen:

Die Verwaltung von Berechtigungen impliziert die entsprechenden Leseberechtigungen (z. B. gewährt der Besitz von manage:users automatisch read:users). Ein Benutzer mit der Rolle SystemRoles.ADMIN besitzt implizit alle Berechtigungen; Berechtigungen ermöglichen es Ihnen, eine Teilmenge von Administratorrechten an Nicht-Administrator-Prinzipale zu delegieren, ohne diese zu vollständigen Administratoren zu machen.

System-Berechtigungen werden über das Admin-Panel erteilt und entzogen.

Principals im Detail

Benutzer

Standard-LibreChat-Konten. Benutzer können lokal (E-Mail/Passwort) oder föderiert (OAuth2, OIDC, SAML, LDAP) sein. Föderierte Benutzer können einer externen Identität (idOnTheSource) zugeordnet werden; für Entra ID ist dies die OID, welche die Gruppensynchronisierung ermöglicht.

Gruppen

Eine Gruppe ist eine benannte Sammlung von Benutzern. LibreChat unterstützt zwei Quellen:

• Lokale Gruppen: werden über das Admin-Panel oder direkt in der Datenbank erstellt und verwaltet. Mitglieder sind LibreChat-Benutzer-IDs.
• Entra ID (Azure AD) Gruppen: werden bei der Anmeldung eines Benutzers via Azure OIDC mit aktiviertem token reuse aus Microsoft Graph synchronisiert. Jede synchronisierte Gruppe speichert ihre Entra Object ID als idOnTheSource, wodurch LibreChat stets mit der Mandantenmitgliedschaft synchron bleibt.

Gruppen können in jeder ACL, in der peoplePicker-Suche sowie als Hauptziel für Konfigurationsüberschreibungen oder Systemberechtigungen erscheinen. Eine einzelne Ressource, die mit einer 500-Personen-Gruppe geteilt wird, entspricht einem einzigen ACL-Eintrag (nicht 500), und Änderungen an der Mitgliedschaft in Entra werden bei der nächsten Anmeldung automatisch übernommen.

Rollen

Jede System- oder benutzerdefinierte Rolle kann als Principal verwendet werden. Das Teilen eines Agents mit einer Rolle (z. B. SupportEngineers) gewährt jedem Benutzer, der diese Rolle aktuell innehat, Zugriff, ohne dass Einzelpersonen aufgezählt werden müssen. Rollen können über interface.peoplePicker.roles aus der Personenauswahl ausgeblendet werden, falls das rollenbasierte Teilen in Ihrer Umgebung ausschließlich Administratoren vorbehalten sein soll.

Öffentlich

Ein spezieller Principal, der mit jedem authentifizierten Benutzer übereinstimmt. Öffentliche Berechtigungen sind nur zulässig, wenn der gewährende Benutzer die SHARE_PUBLIC-Funktionsberechtigung für diesen Ressourcentyp besitzt.

Sichtbarkeit der Personenauswahl

Die Personenauswahl (das Suchfeld in Freigabedialogen) kann auf Instanzebene eingeschränkt werden, um Prinzipaltypen auszublenden, die für Ihre Bereitstellung nicht relevant sind:

interface:
  peoplePicker:
    users: true
    groups: true
    roles: false

Dies betrifft nur die Such-Benutzeroberfläche; bestehende ACL-Einträge für ausgeblendete Prinzipaltypen funktionieren weiterhin und werden wie gewohnt durchgesetzt.

Migrationen von Versionen vor ACL

Versionen vor v0.8.0-rc3 verwendeten ein einfacheres Eigentumsmodell. Ein Upgrade erfordert die Ausführung der ACL-Migration, damit bestehende Agents und Prompts zugänglich bleiben:

Trockenlauf (Änderungen in der Vorschau anzeigen):

npm run migrate:agent-permissions:dry-run
npm run migrate:prompt-permissions:dry-run

Ausführen:

npm run migrate:agent-permissions
npm run migrate:prompt-permissions

Siehe den Leitfaden zur Agenten-Migration für Docker-Varianten und Optionen zur Batch-Größe.

Zugehörige Dokumentation

• Agents: Teilen und Berechtigungen
• Interface-Konfiguration (Funktionsberechtigungen)
• Authentifizierung
• OpenID Connect Token-Wiederverwendung (erforderlich für Entra ID Gruppensynchronisierung)
• Azure / Entra ID OAuth2
• SharePoint-Integration
• Agents API (Remote Agents)
• LibreChat Admin-Panel