API Sessioni

L’API Sessioni fornisce visibilità e controllo sulle sessioni utente nel tenant. Gli amministratori possono elencare le sessioni attive, ispezionare i dettagli delle sessioni, revocare singole sessioni o tutte le sessioni di un utente, e configurare le policy di durata delle sessioni.

Una sessione viene creata quando un utente si autentica con successo (tramite password, magic link, social login o SSO). Ogni sessione tiene traccia del dispositivo, dell’indirizzo IP, dell’ultima attività e del metodo di autenticazione utilizzato. Le sessioni rimangono attive fino alla scadenza, alla revoca da parte di un amministratore, o al logout dell’utente.

Gestione Sessioni

Elenco Sessioni

GET/api/sessionsRequires: manage:sessions

Elenca le sessioni nel tenant. Supporta il filtraggio per ID utente e stato attivo/inattivo. Restituisce i metadati della sessione incluse le informazioni sul dispositivo, l’indirizzo IP e il metodo di autenticazione. Le sessioni sono ordinate per ora dell’ultima attività in ordine decrescente.

Parametri di query

Parametro	Tipo	Descrizione
`page`	integer	Numero di pagina (default: 1)
`limit`	integer	Elementi per pagina (default: 20, max: 100)
`userId`	string	Filtra le sessioni per un utente specifico
`active`	boolean	`true` solo per sessioni attive, `false` solo per scadute/revocate

Risposta di successo


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "sess_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Rossi",
        "ipAddress": "203.0.113.50",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
        "device": "Chrome su macOS",
        "authMethod": "password",
        "isActive": true,
        "createdAt": "2025-02-18T08:00:00Z",
        "lastActivityAt": "2025-02-18T09:45:00Z",
        "expiresAt": "2025-02-19T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

Metodi di autenticazione: password, magic_link, social, sso, device_code, m2m.

Ottieni Sessione

GET/api/sessions/[id]Requires: manage:sessions

Recupera le informazioni dettagliate su una sessione specifica, inclusa la stringa user agent completa, il contesto di autenticazione e i dettagli di revoca se la sessione è stata revocata.

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "sess_abc123",
    "userId": "usr_xyz789",
    "userEmail": "[email protected]",
    "userName": "Alice Rossi",
    "ipAddress": "203.0.113.50",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
    "device": "Chrome su macOS",
    "authMethod": "password",
    "isActive": true,
    "mfaVerified": true,
    "mfaMethod": "totp",
    "acr": "urn:auris:mfa",
    "amr": ["pwd", "otp"],
    "createdAt": "2025-02-18T08:00:00Z",
    "lastActivityAt": "2025-02-18T09:45:00Z",
    "expiresAt": "2025-02-19T08:00:00Z"
  }
}

Campo	Descrizione
`mfaVerified`	Se il 2FA è stato completato per questa sessione
`mfaMethod`	Il metodo 2FA utilizzato (`totp`, `sms`, `webauthn`, o `null`)
`acr`	Authentication Context Class Reference (claim OIDC)
`amr`	Array Authentication Methods Reference (claim OIDC)

Codici di errore

Codice	HTTP	Descrizione
`NOT_FOUND`	404	La sessione non esiste o appartiene a un tenant diverso

Revoca Sessione

DELETE/api/sessions/[id]Requires: manage:sessions

Revoca una sessione specifica. Il refresh token associato viene immediatamente invalidato. L’access token continua a essere valido fino alla sua naturale scadenza (i JWT sono stateless). Per un blocco immediato, combina la revoca della sessione con durate brevi degli access token.

Gli access token sono JWT e non possono essere revocati individualmente senza una blocklist. Auris si affida a durate brevi degli access token (default 15 minuti) per la sicurezza. Quando una sessione viene revocata, il refresh token viene invalidato, quindi l’utente non può ottenere un nuovo access token dopo la scadenza di quello corrente.

Risposta di successo


{
  "ok": true,
  "data": {
    "revoked": true,
    "sessionId": "sess_abc123"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`NOT_FOUND`	404	La sessione non esiste
`ALREADY_REVOKED`	400	La sessione è già stata revocata

Revoca Tutte le Sessioni Utente

POST/api/sessions/revoke-allRequires: manage:sessions

Revoca tutte le sessioni attive per un utente specifico. Questo è utile quando un account potrebbe essere compromesso o quando un amministratore deve forzare un utente a ri-autenticarsi su tutti i dispositivi. Tutti i refresh token associati vengono immediatamente invalidati.

Corpo della richiesta


{
  "userId": "usr_xyz789"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "revoked": true,
    "sessionsRevoked": 3,
    "userId": "usr_xyz789"
  }
}

Il conteggio sessionsRevoked indica quante sessioni attive sono state terminate.

Codici di errore

Codice	HTTP	Descrizione
`VALIDATION_ERROR`	400	Campo `userId` mancante
`NOT_FOUND`	404	L’utente non esiste in questo tenant
`NO_ACTIVE_SESSIONS`	400	L’utente non ha sessioni attive da revocare

La revoca di tutte le sessioni disconnette l’utente da ogni dispositivo e browser. Dovrà ri-autenticarsi su ciascuno. Considera di notificare l’utente via email quando esegui questa operazione.

Statistiche Sessioni

GET/api/sessions/statsRequires: manage:sessions

Ottieni statistiche aggregate delle sessioni per il tenant. Utile per monitorare gli utenti attivi e identificare tendenze.

Risposta di successo


{
  "ok": true,
  "data": {
    "activeSessions": 156,
    "uniqueUsers": 89,
    "last24Hours": {
      "newSessions": 42,
      "expiredSessions": 31,
      "revokedSessions": 3
    },
    "byAuthMethod": {
      "password": 98,
      "magic_link": 23,
      "social": 25,
      "sso": 10
    },
    "byDevice": {
      "desktop": 87,
      "mobile": 52,
      "tablet": 12,
      "unknown": 5
    }
  }
}

Policy di Sessione

Le policy di sessione controllano la durata delle sessioni e dei token nel tenant. Queste impostazioni si applicano a tutti gli utenti, salvo override specifici per applicazione.

Ottieni Impostazioni di Sicurezza

GET/api/settings/securityRequires: manage:security_settings

Recupera le impostazioni correnti di policy di sessione e sicurezza per il tenant.

Risposta di successo


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 86400,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 900,
    "maxConcurrentSessions": 5,
    "requireMfaForAdmin": true,
    "passwordMinLength": 8,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 5,
    "lockoutDuration": 900,
    "updatedAt": "2025-02-10T14:00:00Z"
  }
}

Impostazioni sessione e token

Campo	Tipo	Default	Descrizione
`sessionMaxLifetime`	integer	`86400` (24h)	Durata massima della sessione in secondi, indipendentemente dall’attività
`sessionIdleTimeout`	integer	`3600` (1h)	La sessione scade dopo questo numero di secondi di inattività
`refreshTokenExpiry`	integer	`604800` (7g)	Durata del refresh token in secondi
`accessTokenExpiry`	integer	`900` (15m)	Durata dell’access token in secondi
`maxConcurrentSessions`	integer	`5`	Numero massimo di sessioni attive per utente (0 = illimitato)

Impostazioni MFA

Campo	Tipo	Default	Descrizione
`requireMfaForAdmin`	boolean	`true`	Richiede 2FA per gli utenti con ruoli admin

Impostazioni policy password

Campo	Tipo	Default	Descrizione
`passwordMinLength`	integer	`8`	Lunghezza minima della password
`passwordRequireUppercase`	boolean	`true`	Richiede almeno una lettera maiuscola
`passwordRequireLowercase`	boolean	`true`	Richiede almeno una lettera minuscola
`passwordRequireNumbers`	boolean	`true`	Richiede almeno una cifra
`passwordRequireSpecial`	boolean	`false`	Richiede almeno un carattere speciale
`passwordHistoryCount`	integer	`5`	Numero di password precedenti da controllare (0 = disabilitato)

Impostazioni blocco account

Campo	Tipo	Default	Descrizione
`lockoutThreshold`	integer	`5`	Numero di tentativi di login falliti prima del blocco
`lockoutDuration`	integer	`900` (15m)	Durata del blocco in secondi

Aggiorna Impostazioni di Sicurezza

PUT/api/settings/securityRequires: manage:security_settings

Aggiorna le impostazioni di sessione e policy di sicurezza. Tutti i campi sono opzionali — vengono aggiornati solo i campi forniti. Le modifiche hanno effetto per le nuove sessioni immediatamente. Le sessioni esistenti non vengono influenzate retroattivamente (continuano con i loro tempi di scadenza originali).

Corpo della richiesta


{
  "sessionMaxLifetime": 43200,
  "accessTokenExpiry": 600,
  "maxConcurrentSessions": 3,
  "requireMfaForAdmin": true,
  "passwordMinLength": 12,
  "lockoutThreshold": 3,
  "lockoutDuration": 1800
}

Risposta di successo


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 43200,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 600,
    "maxConcurrentSessions": 3,
    "requireMfaForAdmin": true,
    "passwordMinLength": 12,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 3,
    "lockoutDuration": 1800,
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Codici di errore

Codice	HTTP	Descrizione
`VALIDATION_ERROR`	400	Valore non valido (es. numero negativo, `accessTokenExpiry` > `sessionMaxLifetime`)

Regole di validazione

accessTokenExpiry deve essere tra 60 (1 minuto) e 86400 (24 ore)
refreshTokenExpiry deve essere tra 3600 (1 ora) e 2592000 (30 giorni)
sessionMaxLifetime deve essere >= accessTokenExpiry
sessionIdleTimeout deve essere <= sessionMaxLifetime
maxConcurrentSessions deve essere tra 0 e 100
passwordMinLength deve essere tra 6 e 128
lockoutThreshold deve essere tra 1 e 100
lockoutDuration deve essere tra 60 (1 minuto) e 86400 (24 ore)

Impostare durate molto brevi degli access token (sotto i 5 minuti) aumenta la frequenza delle richieste di refresh token. Impostare durate molto lunghe riduce la sicurezza. L’intervallo consigliato è tra 5 e 30 minuti.

Gestione Sessioni Concorrenti

Quando maxConcurrentSessions è impostato a un valore diverso da zero, Auris impone un limite sul numero di sessioni attive per utente. Quando viene creata una nuova sessione e l’utente ha già il numero massimo di sessioni:

La sessione più vecchia (per createdAt) viene automaticamente revocata.
La nuova sessione viene creata normalmente.
L’utente riceve una notifica che una sessione più vecchia è stata terminata (se le notifiche in-app sono abilitate).

Questo comportamento garantisce che gli utenti non vengano mai impediti di accedere a causa di sessioni obsolete, mantenendo un limite ragionevole sugli accessi concorrenti.

Ciclo di Vita della Sessione


Utente si autentica
       |
       v
  Sessione creata (isActive: true)
       |
       +--- Utente effettua richieste API ---> lastActivityAt aggiornato
       |
       +--- Access token scade ---> Utente aggiorna il token
       |         (refreshToken ancora valido)
       |
       +--- Timeout inattività raggiunto ---> Sessione scaduta
       |
       +--- Durata massima raggiunta ---> Sessione scaduta
       |
       +--- Admin revoca la sessione ---> Sessione revocata
       |
       +--- Utente si disconnette ---> Sessione revocata
       |
       v
  Sessione inattiva (isActive: false)

Riferimento Permessi

Permesso	Descrizione
`manage:sessions`	Elenca, ispeziona e revoca le sessioni nel tenant
`manage:security_settings`	Visualizza e aggiorna le policy di sessione e le impostazioni di sicurezza

I singoli utenti possono visualizzare e revocare le proprie sessioni tramite gli endpoint del profilo utente (GET /api/user/sessions, DELETE /api/user/sessions/[id]) senza necessità di permessi admin. Gli endpoint documentati in questa pagina sono per l’amministrazione a livello di tenant.

Pagine Correlate

Sessioni e Rotazione Token — Come funzionano insieme sessioni, token e rotazione
Guida alla Gestione Sessioni — Configura policy di sessione e applicazione
Gestione Sessioni — Monitora e revoca sessioni dalla Console
API Autenticazione — Endpoint di login e token che creano sessioni