Skip to main content

Token HS256 vs RS256: Quando e Come Usarli

Panoramica​

La piattaforma utilizza due famiglie di token JWT per autenticare attori diversi. L'API Gateway (api.service.js) li valida in sequenza: prima HS256, poi RS256. Comprendere quale token usare e fondamentale per integrare correttamente dispositivi, operatori e utenti amministrativi.

Token HS256 (Simmetrico)​

I token HS256 sono firmati con una chiave segreta condivisa (JWT_SECRET) e vengono generati direttamente dal backend. Sono pensati per comunicazioni machine-to-machine e per operatori di cassa.

Token Dispositivo​

Generato dal servizio licensing durante l'enrollment. Validita: 365 giorni. Contiene deviceId, tenantId, licenseLevel e type: "device".

curl -X POST "https://api.example.com/api/licensing/enroll" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": "AB-1234",
    "deviceInfo": {
      "uuid": "device-uuid-001",
      "platform": "windows",
      "model": "Surface Pro",
      "name": "Cassa 1"
    }
  }'

Risposta: { "deviceToken": "<JWT_HS256>", "config": { ... } }.

Token Operatore​

Generato dal servizio operator-management al login via PIN. Validita: 8 ore. Contiene operatorId, operatorCode, tenantId, role, permissions e type: "operator".

curl -X POST "https://api.example.com/api/operators/login" \
  -H "Authorization: Bearer <DEVICE_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "1234", "deviceId": "device-uuid-001" }'

Token Supporto Tecnico​

Generato dal servizio support-access con issuer pos-backend-support. Include sessionId, techId, scope e viene validato con controllo sessione attiva, JTI blacklist e device binding (X-Device-ID).

Token RS256 (Asimmetrico)​

I token RS256 sono emessi da Keycloak e validati tramite chiave pubblica JWKS. Sono destinati a utenti amministrativi che accedono da pos_admin_console o altre applicazioni web.

# Ottenere token da Keycloak
curl -X POST "https://auth.example.com/auth/realms/pos-enterprise/protocol/openid-connect/token" \
  -d "grant_type=password&client_id=pos-admin&username=admin@demo.com&password=secret"

Il token RS256 contiene i claim standard (sub, preferred_username, email) piu claim personalizzati estratti dai gruppi Keycloak: tenantId, resellerCode e role.

Ordine di Validazione nell'API Gateway​

L'API Gateway tenta la validazione in tre passi:

  1. HS256 con issuer pos-backend -- token dispositivo o operatore
  2. HS256 con issuer pos-backend-support -- token supporto tecnico
  3. RS256 Keycloak -- token utente amministrativo

Se tutti e tre falliscono, la richiesta viene rifiutata con 401 Unauthorized.

Quando Usare Quale Token​

ScenarioTokenGenerato da
App cassa/cameriere (comunicazione device)HS256 Devicelicensing.enroll
Operatore di cassa (login PIN)HS256 Operatoroperator-management.login
Tecnico manutentoreHS256 Supportsupport-access.generateAppToken
Admin console webRS256 KeycloakKeycloak OIDC

FAQ​

D: Posso usare un token RS256 dall'app Flutter cassa? R: Tecnicamente si, ma non e consigliato. L'app cassa deve usare il flusso enrollment (OTP) che genera un token HS256 dispositivo con validita annuale, ottimizzato per scenari offline-first.

D: Come rinnovo un token dispositivo scaduto? R: Chiamare POST /licensing/refresh con il token scaduto. Il backend verifica l'identita del device e genera un nuovo token senza richiedere un nuovo OTP.

D: Il JWT_SECRET deve essere lo stesso su tutti i nodi? R: Si. Tutti i nodi Moleculer devono condividere lo stesso JWT_SECRET (variabile ambiente) per poter validare i token HS256 generati da qualsiasi istanza.

Vedi Anche​

Questa pagina ti è stata utile?