Granular Access Control

LibreChat wordt geleverd met een volledig autorisatiesysteem bovenop de authenticatie. Toegang is niet "alles-of-niets": elke deelbare entiteit in de app (agents, prompts, MCP servers, remote agents, bestanden, conversaties) heeft zijn eigen Access Control List (ACL), en elke functie kan onafhankelijk worden ingeschakeld of beperkt per gebruiker, groep, rol, of openbaar.

Deze pagina legt uit hoe de onderdelen in elkaar grijpen, zodat je machtigingen kunt modelleren die aansluiten bij jouw organisatie: van een klein team waar iedereen vrijelijk deelt, tot een enterprise-implementatie met gesynchroniseerde Entra ID-groepen, aangepaste rollen en gedelegeerde beheerders.

Het toegangsmodel in een oogopslag

De autorisatie van LibreChat bestaat uit drie onafhankelijke lagen die samenwerken:

Alle drie worden geëvalueerd op dezelfde vier hoofdtypen:

• User: een individueel LibreChat-account
• Groep: een verzameling gebruikers (lokaal of gesynchroniseerd vanuit Entra ID)
• Role: een benoemd machtigingsprofiel (bijv. USER, ADMIN, of een aangepaste rol)
• Public: elke geauthenticeerde gebruiker op de instance

Laag 1: Functierechten (Op basis van rollen)

Machtigingen op functieniveau bepalen de volledige mogelijkheden van de app voor een specifieke rol. Ze beantwoorden vragen zoals "Kunnen gebruikers met deze rol überhaupt agents aanmaken?", "Mogen zij prompts openbaar delen?", "Kunnen zij de code-interpreter aanroepen?".

Ingebouwde Systeemrollen

LibreChat wordt geleverd met twee systeemrollen die altijd aanwezig zijn en niet kunnen worden verwijderd:

• ADMIN: toegewezen aan het eerste account dat op de instance is geregistreerd. Admins kunnen elke resource inzien, elke instelling wijzigen, het admin-paneel openen en het gedrag van het hele platform configureren.
• USER: de standaardrol die aan elk nieuw account wordt toegewezen.

Admins kunnen handmatig worden gepromoveerd door het gebruikersdocument in MongoDB bij te werken, zie Administrator Controls.

Permission Types

Elke rol bevat een matrix van toestemmingstypes × acties:

Het onderscheid tussen SHARE en SHARE_PUBLIC is belangrijk: je kunt een rol toestaan om agents te delen met specifieke gebruikers of groepen (SHARE) zonder dat ze agents zichtbaar kunnen maken voor iedereen op de instance (SHARE_PUBLIC).

Functierechten configureren

De aanbevolen manier om functiepermissies te beheren is via het LibreChat Admin Panel, waarmee de permissiematrix direct op elke rol (inclusief eventuele aangepaste rollen die je aanmaakt) wordt bewerkt. Wijzigingen worden doorgevoerd zonder LibreChat opnieuw te implementeren en zijn beperkt tot de specifieke rol die je wilt aanpassen, in plaats van de globale USER standaardinstelling.

Aangepaste rollen

Naast USER en ADMIN kunnen beheerders aangepaste rollen aanmaken met hun eigen matrix van functie-rechten (geïntroduceerd in v0.8.5; zie #12528). Een gebruiker kan meerdere rollen hebben en hun effectieve rechten zijn de vereniging van alle toegekende rollen. Aangepaste rollen worden beheerd vanuit het admin-paneel.

Configuratie-overschrijvingen op basis van rollen en groepen

Naast feature flags introduceerde v0.8.5 een DB-backed configuratie-override systeem (#12354). Hiermee kun je een andere librechat.yaml-stijl configuratie toewijzen aan specifieke groepen of rollen. Een "Research"-groep kan bijvoorbeeld toegang hebben tot extra endpoints, een hogere recursielimiet en andere agent-mogelijkheden dan de standaardconfiguratie. Overrides worden bij het inloggen opgelost en bovenop de basisconfiguratie samengesteld.

Laag 2: Resource ACL's (Delen per entiteit)

Elke deelbare resource in LibreChat heeft zijn eigen Access Control List, onafhankelijk van op rollen gebaseerde rechten. Dit is hoe een individuele gebruiker met SHARE rechten kiest wie toegang krijgt tot hun agent, prompt of MCP server.

Resourcetypen

Resource ACLs zijn momenteel van toepassing op:

• Agents (agent)
• Prompts / Promptgroepen (promptGroup)
• MCP Servers (mcpServer)
• Remote Agents (remoteAgent), voor de Agents API
• Bestanden (file), doorgaans overgenomen van de resource die ze gebruikt
• Projects (project), ondersteunt overerving, zodat resources die met een project worden gedeeld automatisch ACL's overerven

Toegangsrollen (Toestemmingsvoorinstellingen)

In plaats van onbewerkte permissiebits bloot te stellen aan eindgebruikers, gebruikt delen drie benoemde rollen per resourcetype:

Onder de motorkap worden rechten opgeslagen als een bitmask (permBits) voor elk (resource, principal) paar; supersets worden automatisch afgehandeld, dus het verlenen van Editor-rechten impliceert ook Viewer-rechten.

Toegang verlenen vanuit de UI

1. Open de resource (agent builder, prompt form, MCP server settings, enz.)
2. Klik op de Share-knop (zichtbaar wanneer je de eigenaar bent, een beheerder bent, of SHARE-rechten hebt gekregen)
3. In het dialoogvenster voor delen:
   • Gebruik de people picker om te zoeken naar gebruikers, groepen of rollen om toe te voegen
   • Kies een toegangsrol (Viewer / Editor / Owner) per principal
   • Schakel optioneel Public access in om de resource zichtbaar te maken voor iedereen op de instance (vereist de SHARE_PUBLIC feature permission)
4. Opslaan. Ontvangers zien de bron de volgende keer dat ze vernieuwen.

Wat ontvangers zien

• Viewers zien de resource als een kant-en-klaar item in de relevante kiezer (bijv. het dropdownmenu voor agents). Zij kunnen de builder niet openen, de ruwe instructies niet inzien en de instellingen niet wijzigen.
• Editors kunnen de configuratie van de resource openen en wijzigen, maar kunnen deze niet verwijderen of opnieuw delen.
• Eigenaren hebben dezelfde UI als de oorspronkelijke auteur en kunnen vrijelijk verwijderen en opnieuw delen.
• De oorspronkelijke auteur behoudt altijd volledige controle, ongeacht de ACL-status, en beheerders kunnen elke resource op de instance beheren.

Project Erfenis

Rechten kunnen worden overgeërfd van een bovenliggend project. Wanneer een ACL-vermelding wordt overgeërfd, verwijst de inheritedFrom link terug naar de bron. Dit is wat het "Global" project in LibreChat aandrijft, waarbij een resource die aan het globale project is toegevoegd, beschikbaar wordt voor alle gebruikers zonder dat er een vermelding per principal nodig is.

Laag 3: Systeemtoelatingen (Beheerdersmogelijkheden)

Systeemtoelatingen zijn een afzonderlijke toelatingstabel die wordt gebruikt voor beheerdersmogelijkheden, waarmee vragen worden beantwoord zoals "Kan deze gebruiker het beheerderspaneel openen?" of "Kan deze groep MCP-servers wereldwijd beheren?". Ze zijn altijd gekoppeld aan een principal (gebruiker, groep of rol) en een capability-string.

De canonieke mogelijkheden omvatten:

Beheercapaciteiten impliceren hun bijbehorende leescapaciteit (bijv. het bezitten van manage:users verleent automatisch read:users). Een SystemRoles.ADMIN gebruiker bezit impliciet alle capaciteiten; toekenningen stellen je in staat om een subset van beheerdersbevoegdheden te delegeren aan niet-beheerders zonder hen volledige beheerdersrechten te geven.

Systeemtoelatingen worden verleend en ingetrokken via het beheerderspaneel.

Principals in de diepte

Gebruikers

Standaard LibreChat-accounts. Gebruikers kunnen lokaal (e-mail/wachtwoord) of gefedereerd (OAuth2, OIDC, SAML, LDAP) zijn. Gefedereerde gebruikers kunnen worden gekoppeld aan een externe identiteit (idOnTheSource); voor Entra ID is dit de OID, wat de groepsynchronisatie mogelijk maakt.

Groepen

Een groep is een benoemde verzameling gebruikers. LibreChat ondersteunt twee bronnen:

• Lokale groepen: aangemaakt en beheerd vanuit het beheerderspaneel of rechtstreeks in de database. Leden zijn LibreChat gebruikers-ID's.
• Entra ID (Azure AD) groepen: worden gesynchroniseerd vanuit Microsoft Graph wanneer een gebruiker inlogt via Azure OIDC met token reuse ingeschakeld. Elke gesynchroniseerde groep slaat zijn Entra Object ID op als idOnTheSource, wat LibreChat in lijn houdt met het lidmaatschap van de tenant.

Groepen kunnen in elke ACL verschijnen, in peoplePicker zoekopdrachten, en als een principal-doelwit voor configuratie-overschrijvingen of systeemtoekenningen. Eén enkele resource die gedeeld wordt met een groep van 500 personen is één ACL-vermelding (niet 500), en lidmaatschapswijzigingen in Entra worden automatisch doorgevoerd bij de volgende aanmelding.

Rollen

Elk systeem- of aangepaste rol kan worden gebruikt als principal. Het delen van een agent met een rol (bijv. SupportEngineers) geeft elke gebruiker die momenteel die rol heeft toegang, zonder dat individuen hoeven te worden opgesomd. Rollen kunnen worden verborgen in de personenkiezer via interface.peoplePicker.roles voor omgevingen waar het delen op basis van rollen een taak is die alleen voor beheerders is.

Publiek

Een speciale principal die overeenkomt met elke geauthenticeerde gebruiker. Publieke toekenningen zijn alleen toegestaan wanneer de toekennende gebruiker de SHARE_PUBLIC functie-toestemming heeft voor dat resourcetype.

Zichtbaarheid van de People Picker

De people picker (het zoekveld in deelvensters) kan op instantieniveau worden beperkt om principal-types te verbergen die niet relevant zijn voor jouw implementatie:

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

Dit heeft alleen invloed op de search UI; bestaande ACL-vermeldingen voor verborgen principal-types blijven werken en worden normaal afgedwongen.

Migraties van versies van vóór ACL

Versies van vóór v0.8.0-rc3 gebruikten een eenvoudiger eigendomsmodel. Upgraden vereist het uitvoeren van de ACL-migratie zodat bestaande agents en prompts toegankelijk blijven:

Dry run (voorbeeld van wijzigingen):

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

Uitvoeren:

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

Zie de agents migration guide voor Docker-varianten en batch-size opties.

Gerelateerde documentatie

• Agents: Delen en rechten
• Interface-configuratie (functiepermissies)
• Authenticatie
• OpenID Connect Token-hergebruik (vereist voor Entra ID-groepsynchronisatie)
• Azure / Entra ID OAuth2
• SharePoint-integratie
• Agents API (Remote Agents)
• LibreChat-beheerderspaneel