Autenticazione a Due Fattori (2FA)

Panoramica

Il sistema 2FA è stato implementato per aumentare la sicurezza degli account utente. Utilizza TOTP (Time-based One-Time Password) compatibile con le app di autenticazione più comuni come Google Authenticator, Authy, Microsoft Authenticator, ecc.

Architettura

Modello Utente

Il modello User è stato esteso con i seguenti campi:

twoFactorEnabled: Boolean (default: false)
twoFactorSecret: String (select: false) // Non incluso nelle query di default

Endpoint API

1. POST /api/auth/2fa/setup

Genera un nuovo secret TOTP e restituisce il QR code per la configurazione.

Response:

{
  "success": true,
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,..."
}

2. POST /api/auth/2fa/verify

Verifica il token TOTP fornito e abilita il 2FA per l’utente.

Request:

{
  "token": "123456"
}

Response:

{
  "success": true,
  "message": "2FA abilitato con successo"
}

3. POST /api/auth/2fa/disable

Disabilita il 2FA per l’utente corrente.

Response:

{
  "success": true,
  "message": "2FA disabilitato con successo"
}

4. GET /api/auth/2fa/status

Restituisce lo stato corrente del 2FA per l’utente.

Response:

{
  "success": true,
  "twoFactorEnabled": true
}

Flusso di Utilizzo

Abilitazione 2FA

1. L’utente clicca su “Abilita 2FA” nella pagina Impostazioni
2. Il sistema genera un nuovo secret TOTP e un QR code
3. L’utente scansiona il QR code con la sua app di autenticazione
4. L’utente inserisce il codice a 6 cifre generato dall’app
5. Il sistema verifica il codice (con una finestra di tolleranza di ±2 intervalli)
6. Se il codice è valido, il 2FA viene abilitato

Disabilitazione 2FA

1. L’utente clicca su “Disabilita 2FA” nella pagina Impostazioni
2. Il sistema rimuove il secret e disabilita il 2FA
3. L’utente riceve una conferma

Interfaccia Utente

Pagina Impostazioni

• Card “Autenticazione a Due Fattori”: Mostra lo stato corrente (abilitato/disabilitato)
• Indicatore visivo: Pallino verde se abilitato, grigio se disabilitato
• Pulsante “Abilita 2FA”: Apre il dialog di configurazione
• Pulsante “Disabilita 2FA”: Disabilita immediatamente il 2FA
• Dialog di Setup: Mostra il QR code e un campo per inserire il codice di verifica

Sicurezza

• Il twoFactorSecret non viene mai esposto nelle query normali (campo con select: false)
• Viene recuperato esplicitamente solo quando necessario per la verifica
• La verifica dei token utilizza una finestra di tolleranza (window: 2) per gestire piccole differenze di sincronizzazione oraria
• Il secret è codificato in base32 (standard TOTP)

Dipendenze

• speakeasy: Libreria per generazione e verifica TOTP
• qrcode: Libreria per generare QR codes come data URL

TODO / Miglioramenti Futuri

• Implementare backup codes per il recupero account
• Aggiungere la verifica 2FA al flusso di login
• Logging degli accessi con 2FA
• Rate limiting per i tentativi di verifica
• Notifica email quando 2FA viene abilitato/disabilitato
• Possibilità di richiedere 2FA obbligatorio per ruoli specifici