Controllo di accesso granulare

LibreChat viene fornito con un sistema di autorizzazione completo che si aggiunge all'autenticazione. L'accesso non è di tipo "tutto o niente": ogni entità condivisibile nell'app (agenti, prompt, server MCP, agenti remoti, file, conversazioni) ha la propria Access Control List (ACL) e ogni funzionalità può essere abilitata o limitata indipendentemente per utente, gruppo, ruolo o pubblicamente.

Questa pagina spiega come i vari elementi si integrano tra loro, permettendoti di modellare i permessi in base alle esigenze della tua organizzazione: da un piccolo team in cui tutti condividono liberamente, fino a una distribuzione enterprise con gruppi Entra ID sincronizzati, ruoli personalizzati e amministratori delegati.

Panoramica del modello di accesso

L'autorizzazione di LibreChat ha tre livelli indipendenti che si compongono tra loro:

Tutti e tre vengono valutati per gli stessi quattro tipi principali:

• Utente: un account LibreChat individuale
• Gruppo: una raccolta di utenti (locali o sincronizzati da Entra ID)
• Role: un profilo di autorizzazione denominato (ad esempio USER, ADMIN o qualsiasi ruolo personalizzato)
• Pubblico: ogni utente autenticato sull'istanza

Livello 1: Autorizzazioni delle funzionalità (basate sui ruoli)

Le autorizzazioni a livello di funzionalità limitano intere capacità dell'app per un determinato ruolo. Rispondono a domande come "Gli utenti in questo ruolo possono creare agenti?", "Sono autorizzati a condividere prompt pubblicamente?", "Possono invocare l'interprete di codice?".

Ruoli di sistema integrati

LibreChat viene fornito con due ruoli di sistema che sono sempre presenti e non possono essere eliminati:

• ADMIN: assegnato al primo account registrato sull'istanza. Gli amministratori possono vedere ogni risorsa, modificare qualsiasi impostazione, accedere al pannello di amministrazione e configurare il comportamento dell'intera piattaforma.
• USER: il ruolo predefinito assegnato a ogni nuovo account.

Gli amministratori possono essere promossi manualmente aggiornando il documento utente in MongoDB, vedi Administrator Controls.

Tipi di autorizzazione

Ogni ruolo detiene una matrice di tipi di autorizzazione × azioni:

La distinzione tra SHARE e SHARE_PUBLIC è importante: puoi consentire a un ruolo di condividere agenti con utenti o gruppi specifici (SHARE) senza permettere loro di rendere gli agenti visibili a chiunque sull'istanza (SHARE_PUBLIC).

Configurazione dei permessi delle funzionalità

Il modo consigliato per gestire le autorizzazioni delle funzionalità è il Pannello di amministrazione di LibreChat, che modifica direttamente la matrice delle autorizzazioni su ogni ruolo (inclusi eventuali ruoli personalizzati creati). Le modifiche hanno effetto senza dover ridistribuire LibreChat e sono limitate allo specifico ruolo che si desidera modificare, anziché al valore predefinito globale USER.

Ruoli personalizzati

Oltre a USER e ADMIN, gli amministratori possono creare ruoli personalizzati con la propria matrice di autorizzazioni per le funzionalità (introdotta nella v0.8.5; vedere #12528). Un utente può detenere più ruoli e le sue autorizzazioni effettive sono l'unione di tutti i ruoli posseduti. I ruoli personalizzati vengono gestiti dal pannello di amministrazione.

Override di configurazione basati su Ruoli e Gruppi

Oltre ai feature flag, la versione v0.8.5 ha introdotto un sistema di override della configurazione basato su DB (#12354). Questo ti consente di assegnare una configurazione in stile librechat.yaml diversa a gruppi o ruoli specifici. Ad esempio, un gruppo "Ricerca" potrebbe avere accesso a endpoint aggiuntivi, un limite di ricorsione più elevato e funzionalità degli agenti differenti rispetto a quelle predefinite. Gli override vengono risolti al momento del login e composti sopra la configurazione di base.

Layer 2: Resource ACLs (Condivisione per entità)

Ogni risorsa condivisibile in LibreChat ha il proprio Access Control List, indipendente dalle autorizzazioni basate sui ruoli. È così che un singolo utente con autorizzazione SHARE sceglie chi ottiene l'accesso al proprio agent, prompt o server MCP.

Tipi di risorsa

Le ACL delle risorse si applicano attualmente a:

• Agenti (agent)
• Prompt / Gruppi di Prompt (promptGroup)
• Server MCP (mcpServer)
• Agenti Remoti (remoteAgent), per l'Agents API
• File (file), solitamente ereditati dalla risorsa che li utilizza
• Progetti (project), supporta l'ereditarietà in modo che le risorse condivise in un progetto ereditino automaticamente gli ACL

Ruoli di Accesso (Preset di Permessi)

Invece di esporre i bit di permesso grezzi agli utenti finali, la condivisione utilizza tre ruoli denominati per tipo di risorsa:

Sotto il cofano, le autorizzazioni vengono memorizzate come una maschera di bit (permBits) per ogni coppia (risorsa, principale); i superset vengono gestiti automaticamente, quindi concedere l'accesso Editor implica anche quello Viewer.

Concessione dell'accesso dall'interfaccia utente

1. Apri la risorsa (generatore di agenti, modulo di prompt, impostazioni del server MCP, ecc.)
2. Fai clic sul pulsante Share (visibile quando sei il proprietario, un amministratore o ti è stato concesso SHARE)
3. Nella finestra di dialogo di condivisione:
   • Usa il selettore di persone per cercare utenti, gruppi o ruoli da aggiungere
   • Scegli un ruolo di accesso (Viewer / Editor / Owner) per ogni principal
   • Facoltativamente, attiva Accesso pubblico per rendere la risorsa visibile a tutti sull'istanza (richiede l'autorizzazione alla funzionalità SHARE_PUBLIC)
4. Salva. I beneficiari vedranno la risorsa la prossima volta che aggiorneranno la pagina.

Cosa vedono i beneficiari

• I Viewers vedono la risorsa come un elemento pronto all'uso nel selettore pertinente (ad esempio, il menu a discesa degli agenti). Non possono aprire il builder, vedere le istruzioni non elaborate o modificare le impostazioni.
• Gli Editors possono aprire la configurazione della risorsa e modificarla, ma non possono eliminarla o ricondividerla.
• I proprietari hanno la stessa interfaccia utente dell'autore originale e possono eliminare e ricondividere liberamente.
• L'autore originale mantiene sempre il controllo completo indipendentemente dallo stato dell'ACL, e gli amministratori possono gestire qualsiasi risorsa sull'istanza.

Ereditarietà del progetto

Le autorizzazioni possono essere ereditate da un progetto genitore. Quando una voce ACL viene ereditata, il link inheritedFrom punta alla fonte. È questo che alimenta il progetto "Global" in LibreChat, dove una risorsa aggiunta al progetto globale diventa disponibile per tutti gli utenti senza la necessità di una voce per ogni principal.

Layer 3: System Grants (Admin Capabilities)

Le concessioni di sistema (System grants) sono una tabella di concessioni separata utilizzata per le funzionalità a livello di amministratore, che rispondono a domande come "Questo utente può accedere al pannello di amministrazione?" o "Questo gruppo può gestire i server MCP a livello globale?". Sono sempre limitate a un principal (utente, gruppo o ruolo) e a una stringa di funzionalità.

Le funzionalità canoniche includono:

Le funzionalità di gestione implicano la corrispondente funzionalità di lettura (ad esempio, possedere manage:users garantisce automaticamente read:users). Un utente con SystemRoles.ADMIN possiede implicitamente tutte le funzionalità; le concessioni (grants) ti consentono di delegare un sottoinsieme di poteri di amministrazione a soggetti non amministratori senza renderli amministratori a tutti gli effetti.

Le concessioni di sistema (system grants) vengono rilasciate e revocate tramite il pannello di amministrazione.

Principals in Depth

Utenti

Account LibreChat standard. Gli utenti possono essere locali (email/password) o federati (OAuth2, OIDC, SAML, LDAP). Gli utenti federati possono essere associati a un'identità esterna (idOnTheSource); per Entra ID questo è l'OID, che è ciò che abilita la sincronizzazione dei gruppi.

Gruppi

Un gruppo è una raccolta denominata di utenti. LibreChat supporta due fonti:

• Gruppi locali: creati e gestiti dal pannello di amministrazione o direttamente nel database. I membri sono ID utente di LibreChat.
• Gruppi Entra ID (Azure AD): sincronizzati da Microsoft Graph quando un utente effettua l'accesso tramite Azure OIDC con token reuse abilitato. Ogni gruppo sincronizzato memorizza il proprio Entra Object ID come idOnTheSource, il che mantiene LibreChat perfettamente allineato con l'appartenenza al tenant.

I gruppi possono apparire in qualsiasi ACL, nella ricerca peoplePicker e come target principale per override di configurazione o concessioni di sistema. Una singola risorsa condivisa con un gruppo di 500 persone costituisce una sola voce ACL (non 500) e le modifiche all'appartenenza in Entra si propagano automaticamente al login successivo.

Ruoli

Qualsiasi ruolo di sistema o personalizzato può essere utilizzato come entità principale (principal). Condividere un agente con un ruolo (ad esempio SupportEngineers) garantisce l'accesso a ogni utente che attualmente detiene tale ruolo, senza la necessità di elencare i singoli individui. I ruoli possono essere nascosti dal selettore di persone tramite interface.peoplePicker.roles per gli ambienti in cui la condivisione basata sui ruoli è una questione riservata esclusivamente agli amministratori.

Pubblico

Un principal speciale che corrisponde a ogni utente autenticato. Le concessioni pubbliche sono consentite solo quando l'utente che le concede possiede l'autorizzazione alla funzionalità SHARE_PUBLIC per quel tipo di risorsa.

Visibilità del People Picker

Il selettore di persone (la casella di ricerca nelle finestre di dialogo di condivisione) può essere limitato a livello di istanza per nascondere i tipi di entità che non sono rilevanti per la tua distribuzione:

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

Ciò influisce solo sull' interfaccia utente di ricerca; le voci ACL esistenti per i tipi di principal nascosti continuano a funzionare e vengono applicate normalmente.

Migrazioni da versioni precedenti ad ACL

Le versioni precedenti alla v0.8.0-rc3 utilizzavano un modello di proprietà più semplice. L'aggiornamento richiede l'esecuzione della migrazione ACL affinché gli agenti e i prompt esistenti rimangano accessibili:

Dry run (anteprima modifiche):

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

Esegui:

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

Consulta la guida alla migrazione degli agenti per le varianti Docker e le opzioni di batch-size.

Documentazione correlata

• Agenti: Condivisione e Autorizzazioni
• Configurazione dell'interfaccia (permessi delle funzionalità)
• Autenticazione
• Riutilizzo del token OpenID Connect (richiesto per la sincronizzazione dei gruppi Entra ID)
• Azure / Entra ID OAuth2
• Integrazione SharePoint
• API degli Agent (Agent Remoti)
• Pannello di amministrazione di LibreChat