Cercando come si integrano i JWT nell’autenticazione con e-mail e password, si trovano sempre le stesse domande: è sicuro inserire le credenziali in un token? Serve ancora HTTPS? Chi dovrebbe leggere questo token e cosa succede quando scade? Le risposte sono brevi; applicarle correttamente è la parte più importante del lavoro.
Questo tutorial illustra l’intero ciclo di vita di un JSON Web Token in un’app con e-mail e password, dalla prima registrazione alla disconnessione, usando l’API REST AuthFlow™. Il formato del token è definito in RFC 7519; non è necessario leggere lo standard per seguire la guida.
Cos’è un JWT e cosa non è
Un JWT è il risultato dell’autenticazione, non un suo sostituto. L’utente dimostra una volta la propria identità con e-mail e password. Il server restituisce quindi un token firmato che dice: «questa persona si è già autenticata». Ogni richiesta successiva trasporta il token al posto della password. È questo che rende utili i JWT nei sistemi senza stato e distribuiti: qualsiasi servizio con la chiave giusta può verificare il token senza un altro passaggio al database.
Un JWT è composto da tre parti: un header (tipo di token e algoritmo di firma), un payload con i claim sull’utente e una firma. La firma dimostra che il token non è stato alterato. Non nasconde nulla. Il payload è solo codificato in base64, quindi chiunque ottenga il token può leggerlo. Considerate un JWT rilevabile in caso di manomissione, non segreto.
Non inserire mai la password nel token
Una domanda frequente tra chi inizia è se le credenziali di un utente possano essere memorizzate nel JWT. In genere non è necessario: il token è già una credenziale di breve durata generata al momento dell’accesso. Se serve identificare l’utente, inserite un identificativo nel claim sub, oltre a un ruolo o livello di accesso se necessario al backend. Escludete password, segreti e qualsiasi informazione che non vorreste rendere visibile nel browser.
HTTPS è una questione distinta e va usato ovunque. Protegge il traffico tra client e server, mentre la firma del JWT protegge l’integrità del token. Nessuno dei due sostituisce l’altro.
Passaggio 1: mantieni la chiave API sul server
Ogni chiamata ad AuthFlow viene effettuata per conto della tua organizzazione, usando la chiave API disponibile nella dashboard del proprietario. La chiave deve rimanere su un’infrastruttura sotto il tuo controllo, per esempio in una variabile d’ambiente lato server come AUTHFLOW_API_KEY. Non inserirla mai nel JavaScript del browser. La soluzione sicura più semplice è un piccolo backend (oppure il proxy ExpressJS che pubblichiamo) a cui si collega il frontend e che chiama /auth per suo conto.
Passaggio 2: registrati e accedi
Prima di una registrazione o di un accesso, il backend richiede un token anti-abuso di breve durata tramite /auth/fooBar, per l’indirizzo e-mail dell’utente. Scade dopo 45 secondi: recuperalo subito prima della chiamata successiva e non riutilizzarlo mai. Poi chiama /auth/signUp con il valore foobar, il tuo api_key, l’email, una password conforme alla regola di complessità (da 8 a 32 caratteri, con una maiuscola, una minuscola, un numero e un carattere speciale), il fullname e disclaimed impostato su true. Se la registrazione riesce, viene restituito subito un token di sessione; un indirizzo e-mail e un ruolo già esistenti restituiscono 409.
L’accesso funziona allo stesso modo tramite /auth/login. In caso di successo ricevi il token di sessione: un JWT firmato con RS512. RS512 usa una coppia di chiavi. I token vengono firmati con una chiave privata che non vedrai mai e possono essere verificati senza condividere alcun segreto.
Passaggio 3: conserva il token con attenzione
Quando il backend riceve il token, decidi dove conservarlo. I cookie HTTP-only sono l’opzione consigliata perché gli script della pagina non possono leggerli, limitando così i danni di una vulnerabilità di cross-site scripting. Qualunque sia la scelta, conserva il token di sessione, non uno temporaneo, e assicurati che non venga mai scritto nei log.
Passaggio 4: convalida ogni route protetta
Prima di gestire una richiesta protetta, il backend deve controllare il token. Chiama /auth/validate con sessionToken e l’email dell’utente: un token valido viene accettato, mentre uno non valido o scaduto restituisce 401. Usa /auth/me quando serve il profilo dell’utente corrente. È importante effettuare questo controllo sul server per ogni richiesta protetta: una firma che non viene mai verificata non protegge nulla.
La scadenza fa parte del progetto. Quando un token scade, l’utente accede di nuovo invece di lasciare che l’app provi a estenderlo di nascosto. Assicurati che l’app gestisca correttamente il 401 e rimandi l’utente alla schermata di accesso.
Passaggio 5: gestisci l’autenticazione a due fattori
Se un utente ha attivato la 2FA, /auth/login non restituisce un token di sessione. Restituisce invece requires2FA e un tempToken. L’app chiede quindi un secondo fattore e scambia il tempToken tramite uno degli endpoint di verifica /auth/2fa (un codice TOTP, un codice di recupero o un OTP via e-mail). Solo questo scambio produce il vero token di sessione: assicurati quindi di conservare quello e mai il tempToken.
Esegui il debug dei token con jwt.io
Quando qualcosa non va, il modo più rapido per vedere cosa contiene davvero un token è jwt.io. Incollalo nel debugger: l’header e il payload vengono decodificati, così puoi controllare l’algoritmo, il claim sub e l’ora di scadenza. Di solito basta per individuare un token scaduto, l’utente sbagliato o un tempToken salvato per errore.
Da tutto quanto detto finora deriva un’avvertenza: un token è una credenziale. Considera sensibile un token di produzione attivo, preferisci gli account di test per il debug ed evita di incollare token reali in strumenti di cui non ti fidi. Decodificare un token non equivale a verificarlo. La verifica avviene comunque sul server tramite /auth/validate.
Passaggio 6: esci
Per terminare una sessione, chiama /auth/logout con sessionToken ed email, quindi rimuovi il token dal luogo in cui l’hai conservato. Cambiare la password funziona in modo simile tramite /auth/changePassword. Registrare gli eventi di autenticazione durante il processo fornisce una traccia utile in caso di problemi.
Lista di controllo per l’integrazione JWT
- La chiave API si trova solo nella configurazione lato server, mai nel codice del browser.
- Ogni registrazione e accesso è preceduto da una nuova chiamata a
/auth/fooBar. - Nessuna password o segreto viene inserito nel payload del token; gli utenti si identificano con
sube un ruolo. - Il token di sessione è conservato in un cookie HTTP-only o in un altro archivio controllato dal server.
- Ogni route protetta convalida il token tramite
/auth/validateprima di eseguire qualsiasi operazione. - I token scaduti o non validi (401) rimandano l’utente alla schermata di accesso.
- Il flusso 2FA conserva il token di sessione finale, non il
tempToken. - Tutto il traffico usa HTTPS e i token non vengono mai scritti nei log.
Ecco l’intero ciclo: autenticati una volta, trasporta un token firmato, verificalo sul server e lascialo scadere. Consulta la guida introduttiva per il riferimento completo degli endpoint, oppure confronta l’approccio delle altre piattaforme. Se un token sembra sbagliato, jwt.io ti mostrerà cosa contiene.