Progettare un RBAC a 44 permessi per basi di conoscenza AI

Perché le basi di conoscenza AI richiedono un controllo degli accessi reale

Un workspace AI concentra le informazioni operative più sensibili di un'organizzazione: documenti interni, cronologie di chat con citazioni RAG, configurazioni degli agenti e connettori verso sistemi esterni. Quando quella superficie è aperta a un'intera azienda, "chi può vedere cosa" smette di essere una richiesta di funzionalità marginale e diventa un problema della stessa categoria dei permessi sui database: una decisione di progettazione che deve essere corretta per costruzione.

Simmetric Chat la affronta esattamente così. Ogni richiesta autenticata attraversa un controllo di ruolo e permesso prima di toccare i dati di business, e lo stesso modello che protegge la cronologia delle chat governa anche quali parti dell'applicazione un utente può persino vedere nella barra laterale. Questo articolo descrive come il sistema è progettato: i 44 permessi che coprono la superficie delle risorse della piattaforma, le 15 sezioni di menu che mappano quei permessi sull'interfaccia utente e le protezioni a livello di richiesta che impediscono agli utenti autenticati di raggiungere record non di loro competenza.

Il modello di permessi: 44 permessi granulari

Al centro del modello c'è un vocabolario fisso di 44 permessi. Ogni permesso nomina una risorsa e una azione, seguendo la convenzione risorsa:azione. Workspace, progetti, chat e documenti portano ciascuno la tripletta completa lettura/scrittura/eliminazione, perché sono le risorse che gli utenti creano e distruggono nel corso del lavoro ordinario:

• workspace:read, workspace:write, workspace:delete
• project:read, project:write, project:delete
• chat:read, chat:write, chat:delete
• document:read, document:write, document:delete

Intorno a quel nucleo si collocano i permessi per il flusso di creazione stesso (workspace:create, project:create), per l'amministrazione della piattaforma (admin:users, admin:settings, admin:roles) e per la lettura o la configurazione dei provider LLM (provider:read, provider:write). Gli archivi ricevono lo stesso trattamento a tripletta delle risorse centrali, perché le conversazioni archiviate restano comunque dati sensibili.

Un gruppo di sei permessi di backup separa la gestione delle destinazioni, l'esecuzione dei job, l'ispezione dei log e le operazioni di ripristino - la suddivisione conta perché "può avviare un backup" e "può ripristinare dati di produzione in un workspace arbitrario" sono livelli di fiducia diversi. Infine, memory:read e memory:write coprono il sistema di memoria per utente e per workspace, e filters:manage riserva l'amministrazione dei filtri ai soli amministratori.

I permessi sono memorizzati come tabella di enumerazione nel database e richiamati per nome. I ruoli personalizzati si compongono selezionando dall'insieme dei 44 permessi, così un operatore può esprimere un profilo "archivista" o "analista di sola lettura" senza toccare il codice:

{
"name": "archivista",
"permissions": ["workspace:read", "document:read", "archive:read", "chat:read"]
}

Due ruoli predefiniti sono disponibili dall'avvio. Il ruolo admin detiene tutti i 44 permessi; il ruolo user detiene un sottoinsieme operativo - lettura su workspace e provider, lettura/scrittura su chat e documenti, lettura sugli archivi, creazione di workspace e progetti, e piena gestione delle proprie memorie. Nessuno dei due ruoli è trattato in modo speciale nella logica applicativa; entrambi sono righe ordinarie che il middleware dei permessi risolve come qualsiasi altro.

Sezioni di menu: permessi che modellano l'interfaccia

Un controllo degli accessi che protegge solo le rotte API produce un'esperienza confusa - gli utenti cliccano pulsanti che falliscono. Simmetric Chat mappa inoltre i permessi su 15 sezioni di menu che controllano la visibilità della barra laterale. Le sezioni sono l'anatomia strutturale dell'applicazione:

dashboard, chat, documents, knowledgeBase, workspaces, projects, marketplace, mcpConnections, eventLog, analytics, widget, settings e uploads.

Ogni ruolo porta la propria lista di sezioni di menu, memorizzata come stringhe così che nuove sezioni possano essere aggiunte senza migrazioni del database. Un ruolo utente può vedere dashboard, chat, documents, knowledgeBase, workspaces, widget e uploads, mentre il ruolo admin vede tutte e 13. Il risultato è che l'interfaccia stessa riflette ciò che il ruolo può fare: un utente senza permessi di analytics non incontra mai un punto di ingresso analytics su cui cliccare.

I controlli sui permessi e la visibilità dei menu sono due espressioni dello stesso ruolo sottostante, il che significa che c'è un'unica fonte di verità da esaminare durante un audit.

Protezioni a livello di richiesta: RBAC come middleware

Ogni richiesta API risolve l'utente insieme a ruoli e permessi (con una cache) e collega l'identità risolta alla richiesta. Sopra quello si collocano quattro guardie middleware, ognuna delle quali risponde a una domanda diversa:

• requirePermission - gli admin passano sempre; tutti gli altri devono detenere ogni permesso elencato per la rotta. Le richieste non autenticate ricevono 401; gli utenti autenticati senza permessi sufficienti ricevono 403 con un errore esplicito "Permessi insufficienti".
• requireAdmin - barriera rigida per le rotte amministrative, che risponde 403 "Accesso admin richiesto" ai non amministratori.
• requireProjectAccess - un controllo IDOR su proprietà del progetto e righe di accesso esplicite.
• requireWorkspaceAccess - lo stesso tipo di controllo per i workspace, che accetta proprietà del workspace, proprietà del progetto padre o una concessione di accesso esplicita.

Le ultime due meritano enfasi perché affrontano la classe di vulnerabilità che affligge i sistemi multi-tenant. Un attacco IDOR (insecure direct object reference) è ciò che accade quando /api/workspaces/123 si fida dell'identificativo nell'URL più che dell'identità di chi chiama. Un utente autenticato - ma non autorizzato per il workspace 123 - non deve poter leggerne i documenti indovinando identificativi. Simmetric Chat risponde a quelle richieste con 401 quando l'utente non è autenticato e 403 "Permessi insufficienti" quando l'utente semplicemente non ha accesso, invece di rivelare l'esistenza o il contenuto della risorsa.

La protezione delle rotte è dichiarativa. Le operazioni CRUD sui workspace richiedono requireWorkspaceAccess; creare un workspace richiede il permesso workspace:create e rispetta i limiti del piano; l'amministrazione dei ruoli sta dietro a requireAdmin. La tabella delle rotte si legge come la politica di sicurezza, che è esattamente la proprietà che si desidera quando un nuovo ingegnere chiede "cosa può fare questo endpoint?"

Audit trail: sapere chi ha fatto cosa

I controlli sui permessi rispondono a "questa azione dovrebbe essere consentita?"; gli audit trail rispondono a "cosa è effettivamente successo". Simmetric Chat registra una traccia di audit delle azioni significative della piattaforma - eventi di autenticazione, operazioni sui documenti, modifiche alle impostazioni e azioni amministrative - in un log eventi consultabile.

La combinazione è ciò che rende l'RBAC operativo anziché teorico. Quando si verifica un'eliminazione inattesa di un documento, il log eventi identifica l'attore e l'azione; il modello di permessi spiega quale ruolo lo ha consentito; e aggiustare i permessi di un ruolo o le sue sezioni di menu chiude la lacuna. Anche la superficie di audit è a sua volta protetta dai permessi attraverso la sezione di menu eventLog, così che il registro delle attività rilevanti per la sicurezza sia visibile solo ai ruoli che vi sono stati delegati.

Le modifiche sensibili alla conservazione dei dati - come configurare i giorni di retention dei messaggi di chat - sono esse stesse auditate, così che perfino i controlli che governano il ciclo di vita dei dati lasciano la loro traccia.

Come si presenta in pratica

Si consideri un deployment a tre ruoli. Gli amministratori conservano l'intero insieme di 44 permessi e tutte e 13 le sezioni di menu. Un ruolo utente quotidiano lavora entro chat, documenti e i propri workspace, e non vede mai il log eventi né le impostazioni dei provider. Un revisore di conformità ottiene permessi di sola lettura su documenti, chat e archivi, più l'accesso al log eventi - capace di ispezionare tutto, senza poter cambiare nulla.

Nulla di questo ha richiesto di biforcare l'applicazione o di scrivere middleware personalizzato. Ha richiesto di comporre permessi in ruoli e di mappare le sezioni di menu. Questo è l'obiettivo di progettazione che il modello a 44 permessi serve: abbastanza granulare da esprimere confini organizzativi reali, abbastanza semplice da stare in testa.

Per vedere l'intero vocabolario dei permessi e le rotte di gestione dei ruoli, consultate il riferimento API. Per un tour pratico di ruoli, permessi e sezioni di menu nell'interfaccia di amministrazione, vedete la guida all'uso.