Gestione delle Sessioni

Auris gestisce le sessioni utente attraverso una combinazione di token OAuth2 (access token e refresh token) e record di sessione lato server. Questa guida spiega il ciclo di vita delle sessioni, come configurare le policy di sessione, come funziona la rotazione dei token e come revocare le sessioni in modo programmatico.

Ciclo di Vita della Sessione

Quando un utente si autentica tramite il flusso di login ospitato, Auris crea quanto segue:

OAuth Session — Un record lato server che traccia lo stato di autenticazione, memorizzato con un cookie httpOnly sul dominio di login ospitato. Questa sessione ha un TTL di 30 minuti ed è usata solo durante il flusso di login.
Access Token — Un JWT di breve durata (default: 60 minuti) restituito alla tua applicazione. Usato come token Bearer per autenticare le richieste API.
Refresh Token — Un token opaco di lunga durata (default: 30 giorni) usato per ottenere nuovi access token senza richiedere all’utente di effettuare di nuovo il login.
Login Session — Un record lato server in Auris che traccia la sessione attiva, incluse informazioni sul dispositivo, indirizzo IP e i metodi di autenticazione usati (claim acr/amr).

L’access token è la credenziale principale che la tua applicazione usa. Quando scade, l’SDK usa automaticamente il refresh token per ottenere un nuovo access token (se autoRefresh è abilitato). Il refresh token stesso può essere ruotato ad ogni utilizzo per sicurezza aggiuntiva.

Configurare le Policy di Sessione

Le policy di sessione controllano per quanto tempo le sessioni rimangono valide e in quali condizioni scadono. Configurale nella Console Auris sotto Impostazioni poi Sicurezza.

Impostazioni di Durata della Sessione

Impostazione	Default	Descrizione
Durata access token	60 minuti	Per quanto tempo un access token è valido prima di dover essere rinnovato
Durata refresh token	30 giorni	Tempo massimo in cui un refresh token può essere usato per ottenere nuovi access token
Scadenza assoluta sessione	30 giorni	Durata massima della sessione indipendentemente dall’attività
Timeout di inattività	7 giorni	Se un utente non esegue alcuna azione autenticata entro questo periodo, la sessione viene invalidata
Rotazione refresh token	Abilitata	Se abilitata, ogni utilizzo del refresh token emette un nuovo refresh token e invalida il vecchio

Configurazione tramite Console

Naviga su Console poi Impostazioni poi Sicurezza
Nella sezione Policy di Sessione, modifica i valori
Clicca Salva

Le modifiche hanno effetto immediato per le nuove sessioni. Le sessioni esistenti continuano con la policy originale fino alla scadenza.

Configurazione tramite API


curl -X PATCH https://auth.tuodominio.com/api/settings/security \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "accessTokenLifetime": 3600,
    "refreshTokenLifetime": 2592000,
    "absoluteSessionExpiry": 2592000,
    "idleTimeout": 604800,
    "refreshTokenRotation": true
  }'

Tutte le durate sono in secondi.

Durate brevi degli access token (15-30 minuti) combinate con la rotazione dei refresh token forniscono la migliore postura di sicurezza. L’SDK gestisce il refresh automaticamente, quindi durate più brevi non influenzano l’esperienza utente.

Rotazione dei Token

Come Funziona la Rotazione dei Refresh Token

Quando la rotazione dei refresh token è abilitata (consigliata), il flusso di scambio token funziona così:

La tua applicazione invia il refresh token corrente all’endpoint token
Auris valida il refresh token e controlla che non sia stato revocato
Auris emette un nuovo access token e un nuovo refresh token
Il vecchio refresh token viene immediatamente invalidato
La tua applicazione memorizza il nuovo refresh token, sostituendo il vecchio


Client                              Auris Token Endpoint
  |                                        |
  |  POST /api/auth/token                  |
  |  grant_type=refresh_token              |
  |  refresh_token=old_RT_abc123           |
  |--------------------------------------->|
  |                                        |  Valida old_RT_abc123
  |                                        |  Invalida old_RT_abc123
  |                                        |  Emette new_AT + new_RT_def456
  |  { access_token, refresh_token }       |
  |<---------------------------------------|
  |                                        |
  |  (old_RT_abc123 ora non è valido)      |

Perché la Rotazione è Importante

Senza rotazione, un refresh token rubato può essere usato indefinitamente (fino alla scadenza) per generare nuovi access token. Con la rotazione:

Ogni refresh token può essere usato una sola volta
Se un attaccante ruba e usa un refresh token, il prossimo tentativo di refresh dell’utente legittimo fallisce (perché il token è già stato consumato)
Auris rileva questo come anomalia di riutilizzo e può invalidare tutti i token nella famiglia, forzando una nuova autenticazione

Rilevamento del Riutilizzo

Se Auris riceve un refresh token già consumato (che indica furto e replay), esso:

Invalida tutti i refresh token della stessa famiglia di token
Registra un evento di sicurezza nel log di audit
L’utente deve autenticarsi di nuovo su tutti i dispositivi

Questa è la difesa principale contro il furto di refresh token nelle applicazioni browser-based.

Assicurati che la tua applicazione gestisca lo storage dei token in modo atomico. Se una risposta di refresh viene ricevuta ma il nuovo token non viene memorizzato (es. a causa di un crash), il vecchio token è già invalido e l’utente dovrà ri-autenticarsi. L’SDK gestisce questo correttamente con un pattern write-then-ack.

Revoca Programmatica delle Sessioni

Revocare una Sessione Specifica

Per revocare una singola sessione (es. quando un utente clicca “Disconnetti” su un dispositivo specifico):


curl -X DELETE https://auth.tuodominio.com/api/sessions/{sessionId} \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

O dall’SDK:


import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.tuazienda.com',
  clientId: 'tuo-client-id',
})
 
// Disconnetti la sessione corrente
await auris.logout({ returnTo: 'https://tuaapp.com' })

Revocare Tutte le Sessioni di un Utente

In un incidente di sicurezza (account compromesso, credenziali rubate), potresti dover terminare immediatamente tutte le sessioni di un utente su tutti i dispositivi:


curl -X POST https://auth.tuodominio.com/api/users/{userId}/revoke-sessions \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Questa chiamata:

Invalida tutti i refresh token dell’utente
Segna tutte le sessioni attive come revocate
Gli access token dell’utente continueranno a funzionare fino alla scadenza (sono JWT stateless), ma non possono essere rinnovati

Per invalidare immediatamente anche gli access token, il tuo resource server deve verificare lo stato della sessione ad ogni richiesta invece di affidarsi solo alla scadenza del JWT. Il middleware @auris/nextjs fa questo automaticamente tramite la chiamata verifySessionActive().

Forzare la Ri-autenticazione

Per richiedere a un utente di ri-autenticarsi alla prossima interazione senza terminare le sessioni esistenti:


curl -X POST https://auth.tuodominio.com/api/users/{userId}/force-reauth \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Questo invalida tutti i refresh token ma consente agli access token correnti di completare le richieste in corso. La prossima volta che l’SDK tenta un refresh del token, fallirà e reindirizzerà l’utente al login.

Gestione delle Sessioni Multi-Dispositivo

Auris traccia le sessioni per dispositivo, consentendo agli utenti e agli amministratori di visualizzare e gestire le sessioni attive su tutti i dispositivi.

Elenco delle Sessioni Attive

Gli utenti possono visualizzare le proprie sessioni:


curl https://auth.tuodominio.com/api/user/sessions \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Risposta:


{
  "ok": true,
  "data": [
    {
      "id": "sess_abc123",
      "deviceInfo": "Chrome 120 su macOS",
      "ipAddress": "203.0.113.42",
      "location": "Milano, Italia",
      "lastActiveAt": "2026-01-15T14:30:00Z",
      "createdAt": "2026-01-10T09:00:00Z",
      "isCurrent": true
    },
    {
      "id": "sess_def456",
      "deviceInfo": "Safari su iPhone 15",
      "ipAddress": "198.51.100.17",
      "location": "Roma, Italia",
      "lastActiveAt": "2026-01-14T18:00:00Z",
      "createdAt": "2026-01-12T11:00:00Z",
      "isCurrent": false
    }
  ]
}

Revocare la Sessione di un Dispositivo Specifico

Un utente può revocare qualsiasi sessione che non è quella corrente:


curl -X DELETE https://auth.tuodominio.com/api/user/sessions/sess_def456 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Gestione delle Sessioni da Admin

Gli amministratori possono visualizzare e revocare le sessioni per qualsiasi utente nella Console:

Naviga su Utenti e seleziona l’utente
Apri il tab Sessioni
Visualizza tutte le sessioni attive con dispositivo, IP, posizione e ultima attività
Clicca Revoca sulle sessioni individuali o Revoca Tutte per terminare tutte le sessioni

Gli admin possono accedere a questo anche tramite API:


# Elenca tutte le sessioni di un utente (admin)
curl https://auth.tuodominio.com/api/admin/sessions?userId={userId} \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"
 
# Revoca una sessione specifica (admin)
curl -X DELETE https://auth.tuodominio.com/api/admin/sessions/{sessionId} \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: tuo-tenant-id"

Best Practice per la Sicurezza delle Sessioni

Usa durate brevi per gli access token. Gli access token sono stateless e non possono essere revocati individualmente. Mantienili brevi (15-60 minuti) affinché la revoca abbia effetto rapidamente quando i refresh token vengono invalidati.

Abilita la rotazione dei refresh token. Questa è la difesa singola più efficace contro il furto di token. Auris la abilita di default — non disabilitarla a meno che non ci sia una ragione tecnica specifica.

Imposta una scadenza assoluta ragionevole per la sessione. Anche con la rotazione dei refresh token, le sessioni dovrebbero avere un limite superiore. Per la maggior parte delle applicazioni, 30 giorni è un buon default. Per applicazioni ad alta sicurezza (bancario, sanitario), considera 1-7 giorni.

Configura il timeout di inattività. Gli utenti che smettono di usare l’applicazione dovrebbero essere disconnessi automaticamente. Un timeout di inattività di 7 giorni bilancia sicurezza e comodità per la maggior parte dei casi d’uso.

Verifica le sessioni lato server per le operazioni sensibili. Per azioni come cambiare email, abilitare/disabilitare MFA o avviare transazioni finanziarie, chiama l’endpoint di verifica sessione Auris per confermare che la sessione sia ancora attiva e non sia stata revocata:


import { getSession } from '@auris/nextjs/server'
 
export async function transferFunds(req: Request) {
  const session = await getSession()
  if (!session) {
    return Response.json({ error: 'Sessione scaduta' }, { status: 401 })
  }
 
  // La sessione è valida e attiva — procedi
}

Monitora gli eventi di sessione. Iscriviti agli eventi webhook login.succeeded e user.session_revoked per tracciare la creazione e la terminazione delle sessioni nel tuo sistema di audit.

Guide Correlate

Login Ospitato (PKCE) — Come vengono emessi i token durante il flusso di login
Multi-Factor Authentication — Aggiungere un secondo fattore alla creazione della sessione
Protezione dagli Attacchi — Lockout brute-force e rilevamento login sospetti
Rate Limiting — Rate limit API sugli endpoint di autenticazione