Gestione Utenti e Ruoli
La piattaforma POS gestisce l'accesso su tre livelli distinti: utenti Keycloak per l'amministrazione, operatori con PIN per l'uso quotidiano in cassa, e token dispositivo per l'autenticazione delle postazioni. Ogni livello ha ruoli e permessi specifici.
Utenti Keycloak (Amministrazione)
Gli utenti Keycloak sono gestiti centralmente tramite il server SSO e accedono alla console di amministrazione e alle API protette. L'autenticazione avviene tramite JWT con firma RS256.
Gerarchia dei ruoli
| Ruolo | Ambito | Permessi principali |
|---|---|---|
SUPERADMIN | Piattaforma | Gestione completa di tutti i tenant e reseller |
RESELLER_ADMIN | Reseller | Gestione dei tenant associati, manutenzione, installazioni |
TENANT_ADMIN | Tenant | Configurazione completa del ristorante, menu, utenti |
OPERATOR | Tenant | Operazioni di cassa secondo i permessi assegnati |
Il ruolo viene estratto dalla gerarchia dei gruppi Keycloak. Un utente appartenente al gruppo /resellers/RES001/admins avra ruolo RESELLER_ADMIN con resellerCode: RES001. Un utente in /tenants/T001/admins avra ruolo TENANT_ADMIN con tenantId: T001.
Operatori con PIN
Gli operatori sono utenti locali del tenant che accedono al POS tramite un codice PIN numerico. Non richiedono un account Keycloak. Il token operatore e firmato con HS256 e contiene:
- operatorId e operatorCode: identificativi univoci
- tenantId: tenant di appartenenza
- role: ruolo operatore (es.
cassiere,responsabile,admin) - permissions: lista dettagliata dei permessi
Permessi operatore
I permessi controllano le azioni disponibili in cassa:
| Permesso | Descrizione |
|---|---|
discount_apply | Applicare sconti manuali sugli articoli |
discount_global | Applicare sconti sul totale dell'ordine |
void_item | Annullare una riga dell'ordine |
void_receipt | Annullare uno scontrino completo |
reprint | Ristampare scontrini precedenti |
reports_x | Visualizzare il rapporto X |
reports_z | Eseguire la chiusura Z |
cash_drawer | Aprire il cassetto manualmente |
price_override | Modificare il prezzo di un prodotto |
refund | Emettere resi e rimborsi |
Un operatore con ruolo cassiere avra tipicamente i permessi base (vendita, stampa), mentre un responsabile avra accesso a sconti, annullamenti e report.
Token Dispositivo
Ogni postazione POS (cassa, cameriere, kiosk) si autentica con un token dispositivo ottenuto tramite il processo di enrollment della licenza. Il token HS256 contiene deviceId, tenantId, deviceName e licenseLevel.
Il token dispositivo identifica la macchina fisica e viene usato per:
- Associare le configurazioni locali (stampanti, layout) al dispositivo
- Determinare le funzionalita disponibili in base alla licenza
- Tracciare le operazioni per dispositivo
Configurazione in Ambiente di Sviluppo
Per lo sviluppo locale senza Keycloak, impostare nel file .env:
SKIP_AUTH=true
DEV_TENANT_ID=demo
Con SKIP_AUTH=true, tutte le richieste vengono autenticate come utente dev-user con tenantId: demo. Questa modalita non deve mai essere attiva in produzione.
FAQ
Come creo un nuovo operatore? Dalla console amministratore, sezione "Operatori". Assegnare un codice univoco, un PIN, il ruolo e i permessi desiderati. L'operatore sara disponibile su tutte le postazioni del tenant.
Posso avere piu ruoli per lo stesso utente Keycloak? Il sistema assegna un singolo ruolo basato sulla posizione nella gerarchia dei gruppi. Per cambiare ruolo, spostare l'utente nel gruppo appropriato.
Cosa succede se un operatore inserisce il PIN sbagliato? Il sistema nega l'accesso. Non c'e un blocco automatico dopo N tentativi errati a livello applicativo, ma Keycloak puo essere configurato con policy di lockout per gli utenti amministrativi.