L'errore JWT 'Invalid Signature' e altri errori comuni dei token, spiegati

Cosa causa davvero un errore di firma non valida in un JWT, perché è diverso da un token scaduto, e come leggere header e payload di un token per trovare il problema reale in pochi secondi.

Un JWT è composto da tre parti codificate in Base64URL unite da punti — header.payload.signature. Header e payload sono solo JSON codificato e chiunque può leggerli senza alcun segreto; la firma è l'unica parte che dimostra davvero che il token è stato emesso da chi possiede la chiave segreta, ed è da lì che nasce quasi ogni errore JWT confuso.

'Invalid signature' quasi mai significa che il token è malformato

Questo errore significa che il server ha ricalcolato la firma con la propria chiave segreta e ha ottenuto un risultato diverso da quello allegato al token. Struttura e JSON del token sono di solito perfettamente validi — la discrepanza è quasi sempre causata da una di queste tre cose: la chiave segreta usata per verificare non corrisponde a quella usata per firmare (comune subito dopo la rotazione di una chiave o tra ambienti diversi), l'algoritmo nell'header (alg) non corrisponde a quello atteso dal server, oppure il payload è stato alterato o ri-codificato dopo la firma, anche da qualcosa di piccolo come una ri-serializzazione del JSON con ordine delle chiavi o spazi diversi.

'Token expired' è un problema completamente diverso, e molto più semplice

Questo non ha nulla a che fare con la firma — significa che la firma è stata verificata correttamente, ma il claim 'exp' nel payload è una data nel passato. Il token sta funzionando esattamente come previsto. La soluzione è semplicemente ottenere un nuovo token (di solito tramite un flusso di refresh token), non toccare la logica di firma.

'alg: none' e perché dovrebbe sempre essere rifiutato

La specifica JWT tecnicamente permette un valore 'alg' pari a 'none', cioè un token senza alcuna firma. Un server che si fida dell'algoritmo indicato all'interno del token stesso — invece di accettare solo l'algoritmo o gli algoritmi che si aspetta esplicitamente — può essere ingannato ad accettare un token completamente non firmato, creato da un attaccante. Convalida sempre lato server contro una lista esplicita di algoritmi consentiti, non fidarti mai del campo 'alg' del token.

Come debuggarlo davvero in meno di un minuto

Incolla il token in un decodificatore e controlla tre cose in ordine: l''alg' dell'header corrisponde a ciò con cui firma il tuo server, il claim 'exp' è nel futuro, e il payload contiene i claim (come 'sub' o un ruolo personalizzato) che il tuo codice si aspetta di leggere. Nove volte su dieci, il bug è in uno di questi tre campi, non nella crittografia in sé.

Il nostro decodificatore JWT separa istantaneamente header, payload e firma e segnala automaticamente un token scaduto — dato che tutto funziona nel tuo browser, è sicuro incollare un token reale e attivo mentre fai debug di un problema in produzione.