RBAC — ruoli, scope e permessi

Come l'admin di un tenant crea tipi di utenza e dà a ciascuno il permesso di fare determinate operazioni su determinate risorse. Modello: scope (permesso risorsa:azione) organizzati in ruoli, assegnati agli utenti.

Prerequisiti: identità/login già configurati (vedi Autenticazione). Le chiamate di gestione richiedono un utente con scope users:*/roles:* (di norma un admin del tenant) e l'header X-Tenant-Id con l'ambiente su cui operi.

Concetti in 30 secondi

• Area / persona — CLIENTE, AGENTE, CRM-USER (dove entra l'utente).
• Scope — permesso atomico risorsa:azione, es. clienti:read, clienti:write, clienti:delete.
• Ruolo (tipo-utenza) — un insieme di scope, riusabile (es. Operatore Clienti).
• Assegnazione — a un utente assegni uno o più ruoli; i permessi effettivi = unione degli scope dei ruoli.

Chi fa cosa: l'associazione endpoint → scope è definita dalla piattaforma (in codice, uguale per tutti i tenant). L'admin del tenant crea ruoli e assegna utenti, scegliendo tra gli scope disponibili.

---

Procedura completa — gestione CLIENTI

Obiettivo: tre tipi di utenza sui clienti — chi legge, chi modifica, chi può anche cancellare — e assegnarli.

Tutte le chiamate: base https://api.base9.app, header Authorization: Bearer <id_token-admin> e X-Tenant-Id: <tuo-tenant>.

1. Guarda gli scope disponibili

curl -H "$AUTH" -H "$TENANT" https://api.base9.app/v1/scopes
# → { "data": { "scopes": ["clienti:read","clienti:write","clienti:delete", ...] } }

2. Crea i tipi di utenza (ruoli)

# sola lettura
curl -X POST -H "$AUTH" -H "$TENANT" -H "Content-Type: application/json" \
  -d '{"role_id":"clienti_ro","label":"Clienti — sola lettura","scopes":["clienti:read"]}' \
  https://api.base9.app/v1/roles

# lettura + scrittura
curl -X POST -H "$AUTH" -H "$TENANT" -H "Content-Type: application/json" \
  -d '{"role_id":"clienti_rw","label":"Clienti — gestione","scopes":["clienti:read","clienti:write"]}' \
  https://api.base9.app/v1/roles

# gestione completa (incl. cancellazione)
curl -X POST -H "$AUTH" -H "$TENANT" -H "Content-Type: application/json" \
  -d '{"role_id":"clienti_full","label":"Clienti — responsabile","scopes":["clienti:read","clienti:write","clienti:delete"]}' \
  https://api.base9.app/v1/roles

3. Crea l'utente

curl -X POST -H "$AUTH" -H "$TENANT" -H "Content-Type: application/json" \
  -d '{"email":"mario.rossi@example.com"}' https://api.base9.app/v1/users
# → { "data": { "sub": "e4f1…", "email": "mario.rossi@example.com" } }

4. Assegna il tipo-utenza (area CRM + ruolo)

curl -X PUT -H "$AUTH" -H "$TENANT" -H "Content-Type: application/json" \
  -d '{"role":"operatore","roles":["clienti_rw"]}' \
  https://api.base9.app/v1/users/<sub>/grants/CRM-USER

Da questo momento Mario, effettuato il login, può leggere e modificare i clienti, ma non cancellarli.

5. Cosa succede quando Mario usa l'API

Mario fa login (POST /v1/auth/login), sceglie l'ambiente e invia X-Tenant-Id. Le sue chiamate ai clienti sono autorizzate automaticamente dagli scope:

Chiamata	Scope richiesto	Esito per clienti_rw
GET /v1/clienti	clienti:read	✅ 200
POST /v1/clienti	clienti:write	✅ 200
PUT /v1/clienti/{id}	clienti:write	✅ 200
DELETE /v1/clienti/{id}	clienti:delete	🚫 403 (serve lo scope 'clienti:delete')

Il frontend può nascondere il pulsante "Elimina" leggendo gli scope da GET /v1/me/context.

6. Cambiare i permessi in seguito

• Promuovere Mario a responsabile → assegna clienti_full:

  curl -X PUT -H "$AUTH" -H "$TENANT" -d '{"role":"operatore","roles":["clienti_full"]}' \
    https://api.base9.app/v1/users/<sub>/grants/CRM-USER

• Aggiungere la cancellazione a TUTTI gli "operatore clienti" → modifica il ruolo (vale subito per tutti):

  curl -X PUT -H "$AUTH" -H "$TENANT" -d '{"scopes":["clienti:read","clienti:write","clienti:delete"]}' \
    https://api.base9.app/v1/roles/clienti_rw

• Sospendere / riattivare / rimuovere l'utente:

  curl -X POST   -H "$AUTH" -H "$TENANT" https://api.base9.app/v1/users/<sub>/disable
  curl -X POST   -H "$AUTH" -H "$TENANT" https://api.base9.app/v1/users/<sub>/enable
  curl -X DELETE -H "$AUTH" -H "$TENANT" https://api.base9.app/v1/users/<sub>

I permessi sono risolti lato server a ogni chiamata (cache breve): una modifica a un ruolo è effettiva entro un minuto, senza re-login.

---

Note

• Admin: un utente CRM-USER con ruolo admin bypassa i controlli sui moduli del proprio tenant (non serve elencargli gli scope).
• Integrazioni (API key dmk_*): usano gli stessi endpoint; il permesso deriva dallo scope della key (lettura/scrittura), il tenant è quello legato alla key (niente header).
• Riferimento endpoint: vedi l'API Reference, tag RBAC.