# Utenti, ruoli e permessi {#users-roles-permissions}
SnapOtter include tre ruoli integrati, 17 permessi granulari e il supporto per ruoli personalizzati con controllo opzionale dell'accesso per singolo strumento. Questa pagina copre l'intero modello di autorizzazione, lo scope delle chiavi API, la gestione dei team e il logging di audit.
Gli amministratori possono creare utenti tramite il pannello di amministrazione o l'endpoint `POST /api/auth/register`. Ogni utente ha un nome utente, un ruolo, un'assegnazione a un team e un indirizzo email opzionale.
### Amministratore predefinito {#default-admin}
Al primo avvio SnapOtter crea un account amministratore predefinito. Le credenziali provengono da variabili d'ambiente:
| Variabile | Predefinito | Descrizione |
|---|---|---|
| `DEFAULT_USERNAME` | `admin` | Nome utente per l'account amministratore iniziale |
Imposta `AUTH_ENABLED=false` per disabilitare completamente l'autenticazione. In questa modalità viene usato un utente anonimo sintetico con ruolo `admin` per tutte le richieste. Non è richiesto alcun accesso.
::: warning
Disabilitare l'autenticazione concede pieno accesso da amministratore a chiunque possa raggiungere l'istanza. Usalo solo in ambienti fidati.
:::
## Ruoli integrati {#built-in-roles}
SnapOtter include tre ruoli integrati. Non possono essere modificati né eliminati.
### Admin {#admin}
Tutti e 17 i permessi. Controllo completo sull'istanza.
| `compliance:manage` | Gestire il ciclo di vita e le funzionalità di conformità del GDPR; le operazioni utente distruttive rimangono limitate all'autorità |
| `webhooks:manage` | Configurare i webhook in uscita |
| `security:manage` | Gestire le impostazioni di sicurezza (allowlist IP, imposizione SSO) |
## Ruoli personalizzati {#custom-roles}
Gli amministratori con il permesso `security:manage` possono creare ruoli personalizzati tramite il pannello di amministrazione o l'API dei ruoli. L'elenco dei ruoli richiede `audit:read`.
### Creazione di un ruolo personalizzato {#creating-a-custom-role}
```bash
curl -X POST http://localhost:1349/api/v1/roles \
-H "Authorization: Bearer si_..."\
-H "Content-Type: application/json"\
-d '{
"name": "reviewer",
"description": "Can use tools and view all files",
Tutte le 17 autorizzazioni possono essere delegate tramite ruoli personalizzati, ma un'autorizzazione amministrativa non rende tale ruolo equivalente al ruolo `admin` integrato. Le mutazioni dell'utente autorizzate da `users:manage`, le operazioni distruttive autorizzate da `compliance:manage` e la gestione dei ruoli personalizzati autorizzata da `security:manage` sono vincolate dall'attuale autorità dell'attore:
- I ruoli integrati seguono `admin` > `editor` > `user`; i ruoli personalizzati sono sotto i ruoli integrati.
- Le autorizzazioni del target devono essere contenute nelle autorizzazioni **effettive** dell'attore. Una chiave API con ambito pertanto non può esercitare le autorizzazioni omesse dal suo ambito.
- L'accesso allo strumento di un ruolo target deve essere contenuto dall'accesso allo strumento stesso dell'attore.
- Un account disabilitato viene confrontato con il suo ruolo originale quando tale ruolo viene registrato come `disabled:<original-role>`.
- L'eliminazione di un ruolo personalizzato richiede anche l'autorizzazione per assegnare il fallback `user` integrato; i membri disabili rimangono disabilitati come `disabled:user`.
Le credenziali globali e la configurazione sono più rigorose: l'emissione o la revoca del token SCIM e l'importazione della configurazione dell'istanza richiedono il ruolo `admin` integrato con completa autorità di amministrazione effettiva.
| `tool` | Limita per ID del singolo strumento | Richiede la funzionalità enterprise `per_tool_permissions` |
Quando è impostata la modalità `tool` ma la funzionalità enterprise non è disponibile, SnapOtter si degrada in modo controllato e consente l'accesso a tutti gli strumenti.
```json
{
"name":"image-only",
"permissions":["tools:use","files:own"],
"toolPermissions":{
"mode":"category",
"allowed":["image"]
}
}
```
### Eliminazione di un ruolo personalizzato {#deleting-a-custom-role}
Quando un ruolo personalizzato viene eliminato, tutti gli utenti ad esso assegnati vengono automaticamente riassegnati al ruolo `user`.
## Team {#teams}
I team raggruppano gli utenti per la gestione dell'archiviazione e della conservazione. Un team `Default` viene creato al primo avvio.
| Campo | Tipo | Descrizione |
|---|---|---|
| `name` | string | Nome univoco del team (1-50 caratteri) |
| `storageQuota` | number | Limite di archiviazione per team in byte (funziona senza enterprise) |
| `retentionHours` | number | Elimina automaticamente gli output dopo questo numero di ore (richiede `team_retention_overrides`, enterprise) |
| `legalHold` | boolean | Impedisce l'eliminazione automatica dei file dei membri del team (richiede `legal_hold`, enterprise) |
::: info
Il team `Default` non può essere eliminato. I team che hanno ancora membri non possono essere eliminati. Riassegna prima i membri.
:::
## Chiavi API {#api-keys}
Gli utenti possono generare chiavi API per l'accesso programmatico. Ogni chiave usa il prefisso `si_` e viene mostrata una sola volta al momento della creazione.
### Permessi con scope {#scoped-permissions}
Le chiavi API possono facoltativamente portare un array `permissions`. Quando è impostato, i permessi effettivi per una richiesta sono l'**intersezione** tra i permessi del ruolo dell'utente e i permessi con scope della chiave. Questo significa che una chiave API non può mai superare i permessi propri dell'utente.
```bash
curl -X POST http://localhost:1349/api/v1/api-keys \
-H "Authorization: Bearer si_..."\
-H "Content-Type: application/json"\
-d '{
"name": "CI pipeline key",
"permissions": ["tools:use", "files:own"],
"expiresAt": "2027-01-01T00:00:00Z"
}'
```
### Scadenza {#expiration}
Le chiavi accettano un timestamp `expiresAt` opzionale. Le chiavi scadute vengono rifiutate al momento dell'autenticazione.
## Log di audit {#audit-log}
SnapOtter registra gli eventi rilevanti per la sicurezza in un log di audit strutturato memorizzato nella tabella di database `audit_log`.
### Visualizzazione del log di audit {#viewing-the-audit-log}
```
GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z
```
Richiede il permesso `audit:read`. Supporta la paginazione (`page`, `limit`) e i filtri (`action`, `ip`, `from`, `to`).
### Audit delle operazioni sugli strumenti {#tool-operation-auditing}
::: warning
Gli eventi `TOOL_EXECUTED`**non** vengono registrati per impostazione predefinita. Sono attivabili tramite uno di due percorsi:
1. Imposta l'impostazione di amministrazione `auditToolOperations` su `true`.
2. Possiedi una licenza attiva con la funzionalità `audit_export` (disponibile sia sui piani team sia enterprise).
Senza uno di questi, le singole esecuzioni degli strumenti non vengono registrate nel log di audit.
:::
### Esportazione {#exporting}
```
GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
```
Richiede il permesso `audit:read` e la funzionalità enterprise `audit_export` (disponibile sia sui piani team sia enterprise). Supporta i formati CSV e JSON, filtrati per `action`, `actorId`, `targetType`, `targetId`, `from` e `to`.
### Firma resistente alla manomissione {#tamper-resistant-signing}
Quando è abilitata, ogni voce del log di audit viene firmata con un HMAC derivato da `DATA_ENCRYPTION_KEY`. Questo richiede:
1. Impostare `DATA_ENCRYPTION_KEY` nel tuo ambiente.
2. Abilitare l'impostazione di amministrazione `tamperResistantAudit`.
3. Una licenza enterprise con la funzionalità `tamper_resistant_audit`.
### Conservazione {#retention}
Imposta `AUDIT_RETENTION_DAYS` per eliminare automaticamente le voci vecchie. Il valore predefinito è `0`, il che significa che le voci vengono conservate a tempo indeterminato.
Le sessioni sono basate su cookie, controllate da `SESSION_DURATION_HOURS` (predefinito: 168 ore / 7 giorni).
### Le modifiche di ruolo invalidano le sessioni {#role-changes-invalidate-sessions}
Quando un amministratore cambia il ruolo di un utente, tutte le sessioni attive di quell'utente vengono eliminate. L'utente deve accedere di nuovo per acquisire i nuovi permessi.
### Protezioni di sicurezza {#safety-guards}
- **Protezione dell'ultimo amministratore**: l'ultimo amministratore rimasto non può essere retrocesso a un ruolo inferiore. L'API restituisce un errore se ci provi.
- **Prevenzione dell'auto-eliminazione**: gli amministratori non possono eliminare il proprio account tramite l'API.
