I Token Spiegati

Auris usa tre categorie di token: token di accesso, refresh token e ID token. Capire cosa fa ogni token, cosa contiene e come deve essere gestito è essenziale per costruire integrazioni sicure.

Token di Accesso

Il token di accesso è la credenziale che la tua applicazione usa per chiamare le API protette. È di breve durata per design — la scadenza default è 15 minuti.

Cos’è

Un token di accesso è un JWT firmato (JSON Web Token). È autocontenuto: il resource server può verificarne l’autenticità controllando la firma senza effettuare una chiamata di rete ad Auris, usando le chiavi pubbliche dall’endpoint JWKS.

Cosa contiene

Un payload decodificato di un token di accesso Auris appare così:


{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "il-tuo-client-id",
  "iat": 1739880000,
  "exp": 1739880900,
  "jti": "tok_xyz789",
  "type": "user",
  "email": "[email protected]",
  "roles": ["editor", "viewer"],
  "scope": "openid profile email",
  "plan": "enterprise"
}

Claim	Descrizione
`sub`	Subject — l’ID utente (univoco all’interno del tenant)
`iss`	Issuer — l’URL dell’istanza Auris
`aud`	Audience — il client ID dell’applicazione
`iat`	Issued At — timestamp Unix di quando il token è stato emesso
`exp`	Expiry — timestamp Unix di quando il token scade
`jti`	JWT ID — identificatore univoco per questo token
`type`	`"user"` per utenti regolari, `"m2m"` per token client credentials
`email`	Indirizzo email dell’utente
`roles`	Array di nomi di ruoli assegnati all’utente
`scope`	Scope concessi separati da spazi
Custom claim	Eventuali claim aggiuntivi configurati tramite Custom Claims nella Console

Come usarlo

Invia il token di accesso nell’header Authorization su ogni richiesta a un’API protetta:


Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS1pZC0xIn0...

Quando scade

I token di accesso scadono dopo 15 minuti per default. Quando un’API restituisce 401 Unauthorized con codice di errore TOKEN_EXPIRED, usa il refresh token per ottenere un nuovo token di accesso. Gli SDK Auris gestiscono questo automaticamente quando autoRefresh: true è configurato.

Refresh Token

Il refresh token consente alla tua applicazione di ottenere nuovi token di accesso senza richiedere all’utente di accedere di nuovo.

Cos’è

Un refresh token è una stringa opaca — non porta nessun claim e non può essere decodificato. È un valore casuale che Auris archivia e valida internamente. La sua opacità è intenzionale: deve essere inviato ad Auris per ottenere qualcosa di utile.

Un refresh token appare così:


rt_7fKp2mXa9qN3vB8yR4tL1wC6jD5sE0uH

Durata default

I refresh token scadono dopo 7 giorni di inattività per default. Se l’utente è attivo, il token viene ruotato ad ogni uso e la scadenza si azzera. Gli amministratori del tenant possono configurare la scadenza nella Console Auris in Impostazioni → Sicurezza → Policy di Sessione.

Rotazione

Auris usa la rotazione del refresh token: ogni volta che scambi un refresh token per nuovi token, il vecchio refresh token viene immediatamente invalidato e ne viene emesso uno nuovo. Questo limita la finestra di esposizione se un refresh token viene rubato.


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_NUOVO_token_ruotato...",
    "expiresIn": 900
  }
}

Considerazioni di Sicurezza

Archivia i refresh token in cookie httpOnly (non accessibili a JavaScript) quando possibile
Se li archivi in memoria o in localStorage, accetta il compromesso di rischio XSS
Non includere mai i refresh token negli URL o nei file di log
La breve durata del token di accesso limita i danni se viene intercettato — il refresh token è la credenziale di maggior valore

ID Token

L’ID token è un concetto OIDC. Viene emesso insieme al token di accesso quando viene richiesto lo scope openid.

Cos’è

Un ID token è un JWT firmato contenente i claim di identità dell’utente. È destinato ad essere consumato dall’applicazione client — non inviato alle API. Le API devono verificare il token di accesso, non l’ID token.

Cosa contiene


{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "il-tuo-client-id",
  "iat": 1739880000,
  "exp": 1739883600,
  "email": "[email protected]",
  "email_verified": true,
  "name": "Alice Rossi",
  "given_name": "Alice",
  "family_name": "Rossi",
  "picture": "https://cdn.esempio.com/avatars/alice.jpg"
}

Quando usarlo

Visualizzare il nome e l’avatar dell’utente nella tua UI senza una chiamata API extra
Verificare l’identità dell’utente in un’applicazione server-side rendered
Passare il contesto utente a widget di terze parti che accettano token OIDC

Non usare l’ID token per autorizzare le chiamate API.

Struttura JWT

Tutti i JWT (token di accesso e ID token) condividono la stessa struttura a tre parti, separate da punti:


header.payload.signature

Ogni parte è codificata in Base64URL (Base64 URL-safe senza padding).

Header


{
  "alg": "RS256",
  "kid": "key-id-1",
  "typ": "JWT"
}

Campo	Descrizione
`alg`	Algoritmo di firma (`RS256` o `HS256`)
`kid`	Key ID — identifica quale chiave pubblica usare per la verifica (da JWKS)
`typ`	Tipo token — sempre `JWT`

Firma

Per RS256: RSASHA256(base64url(header) + "." + base64url(payload), privateKey)

La firma garantisce che il token non sia stato manomesso. Chiunque può decodificare header e payload (sono solo Base64), ma solo Auris (che detiene la chiave privata) può produrre una firma valida.

Decodificare un JWT non lo valida. Verifica sempre la firma rispetto alla chiave pubblica prima di fidarti dei claim. Usa una libreria JWT o l’SDK Auris — non decodificare mai i token manualmente in produzione senza verifica.

Algoritmi di Firma

Auris supporta due algoritmi di firma, configurati tramite la variabile d’ambiente JWT_ALGORITHM:

RS256 (Consigliato)

RSA + SHA-256. Asimmetrico — Auris firma con una chiave privata, i resource server verificano con la chiave pubblica. La chiave pubblica è esposta tramite l’endpoint JWKS.

Vantaggi:

I resource server possono verificare i token localmente senza contattare Auris
La chiave privata non lascia mai il server Auris
Supporto standard in tutte le principali librerie JWT

HS256

HMAC + SHA-256. Simmetrico — lo stesso segreto viene usato sia per la firma che per la verifica. Sia Auris che il resource server devono conoscere il segreto condiviso.

Auris supporta HS256 per compatibilità con alcune integrazioni legacy. RS256 è fortemente preferito per i nuovi deployment.

Verifica JWKS

I resource server verificano i token di accesso recuperando le chiavi di firma dall’endpoint JWKS e usandole per validare la firma JWT localmente.

Endpoint JWKS


GET /.well-known/jwks.json

Risposta


{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM...",
      "e": "AQAB"
    }
  ]
}

Passaggi di Verifica

Decodifica l’header JWT (senza verificare la firma) per estrarre il kid (key ID)
Recupera l’endpoint JWKS (o usa una versione in cache — TTL consigliato: 1 ora)
Trova la chiave nella risposta JWKS il cui kid corrisponde al kid dell’header
Usa quella chiave pubblica per verificare la firma JWT
Verifica che exp sia nel futuro, iss corrisponda al tuo dominio Auris, aud corrisponda al tuo client ID

La maggior parte delle librerie JWT gestisce i passaggi 1-5 automaticamente quando viene fornito un URL JWKS. Esempio usando la libreria jose:


import { createRemoteJWKSet, jwtVerify } from 'jose'
 
const JWKS = createRemoteJWKSet(
  new URL('https://api.altovar.net/.well-known/jwks.json')
)
 
async function verifyToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'https://api.altovar.net',
    audience: 'il-tuo-client-id',
  })
  return payload
}

Rotazione delle Chiavi

Auris ruota periodicamente le chiavi di firma per limitare l’impatto di una compromissione della chiave. Quando avviene la rotazione:

Viene generata una nuova coppia di chiavi RSA e aggiunta all’endpoint JWKS con un nuovo kid
I nuovi token vengono firmati con la nuova chiave
I vecchi token (firmati con la vecchia chiave) continuano a essere validi perché la vecchia chiave pubblica rimane nella risposta JWKS
La vecchia chiave viene rimossa dal JWKS solo dopo che tutti i token firmati con essa sono scaduti

Ciclo di Vita del Token


Login
  → Ricevi token di accesso (15 min) + refresh token (7 giorni) + ID token (1 ora)
  ↓
Usa il token di accesso nelle chiamate API
  ↓
Il token di accesso scade (401 TOKEN_EXPIRED)
  ↓
Scambia il refresh token → nuovo token di accesso + nuovo refresh token
  ↓
Continua a usare il nuovo token di accesso
  ↓
L'utente si disconnette / il refresh token scade / il refresh token viene revocato
  ↓
L'utente deve autenticarsi di nuovo

Best Practice di Archiviazione

Applicazioni Browser (SPA)

Archiviazione	Sicurezza	Note
Cookie `httpOnly`	Massima	Non accessibile a JavaScript — protegge dagli attacchi XSS
`sessionStorage`	Media	Cancellato alla chiusura della scheda. Vulnerabile a XSS.
`localStorage`	Media	Persiste tra le sessioni. Vulnerabile a XSS.
Frammento URL / query string	Minima	Non farlo mai — i token appaiono nella cronologia del browser

Applicazioni Lato Server

Archivia il refresh token nella sessione lato server dell’utente (crittografata a riposo). Emetti token di accesso a breve durata su richiesta e memorizzali in cache in memoria per la loro durata rimanente. Non archiviare mai i token di accesso nel database.

Applicazioni Mobile

Usa l’archiviazione sicura delle credenziali della piattaforma:

iOS: Keychain Services
Android: Android Keystore
React Native: react-native-keychain o Expo SecureStore

Non archiviare mai i token in AsyncStorage su mobile — non è crittografato.

L’SDK React di Auris (@auris/react) gestisce automaticamente l’archiviazione dei token. A meno che tu non stia implementando un’integrazione personalizzata, non devi gestire tu stesso l’archiviazione dei token.

Concetti Correlati

OAuth 2.0 & OIDC — Il layer del protocollo che emette i token
Flusso PKCE — Come i token vengono ottenuti tramite Authorization Code + PKCE
Sessioni & Rotazione Token — Ciclo di vita delle sessioni e rotazione del refresh token
DPoP (Proof of Possession) — Binding dei token a chiavi crittografiche
Custom JWT Claims — Aggiungere claim personalizzati ai token di accesso