Cos’è un JWT: decodificare non è verificare

Un JSON Web Token (JWT) è composto da tre parti di testo unite da punti: un header, un payload e una firma. Le prime due sono solo codificate, non cifrate, quindi chiunque possieda il token può leggerle. La firma permette a un server di verificare che il token sia stato emesso da una parte fidata e che nessuno l’abbia modificato. Decodificare un token ti dice che cosa afferma. Solo verificarlo ti dice se puoi fidarti.

Decodificatore JWTToken scaduto o ancora valido?Usalo gratis

Le tre parti

Un token ha questa forma: header.payload.signature. La prima parte del noto token di esempio di jwt.io è:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Ciascuna delle prime due parti è un JSON convertito in base64url, una forma di testo sicura per gli URL. La prima parte si decodifica in:

{"alg":"HS256","typ":"JWT"}

Il payload dello stesso esempio si decodifica in:

{"sub":"1234567890","name":"John Doe","iat":1516239022}

Il payload contiene i claim, cioè affermazioni sull’utente o sulla sessione. La firma è calcolata a partire dalle prime due parti e da una chiave, quindi cambiare anche un solo carattere la rende non più valida. Base64url si inverte senza bisogno di chiavi, perciò non mettere mai una password, una chiave privata o dati personali nel payload.

Claim registrati

La RFC 7519, lo standard dei JWT, riserva alcuni nomi brevi per i claim:

• iss (issuer): chi ha creato il token.
• sub (subject): a chi si riferisce il token, di solito un ID utente.
• aud (audience): il servizio a cui il token è destinato.
• exp (expiration time): il momento dopo il quale il token non è più valido.
• nbf (not before): il primo momento in cui il token è valido.
• iat (issued at): quando il token è stato creato.

I tempi sono secondi trascorsi dal 1° gennaio 1970 UTC, detti tempo Unix. L’esempio non ha exp, quindi secondo lo standard non scade mai. Un token reale dovrebbe averlo. Altri nomi, come role o email, sono definiti dall’applicazione.

Decodificare non è verificare

Decodificare significa dividere il token in corrispondenza dei punti, invertire il base64url e leggere il JSON. Mostra ciò che il token afferma, e lo fa anche per un token falsificato, perché chiunque può scrivere qualsiasi claim con qualsiasi firma.

Verificare ricalcola la firma con la chiave corretta e controlla che coincida. Controlla anche che exp e nbf includano l’ora attuale e che iss e aud siano i valori attesi dal servizio. Un’app che legge un claim role senza verificarlo si fida di chiunque abbia scritto il token. È un errore comune.

HS256, RS256 e ES256

Il valore alg indica il metodo. Tre sono i più diffusi:

• HS256 è HMAC con SHA-256. Un unico segreto condiviso firma e verifica, quindi il segreto deve restare sul server che emette i token.
• RS256 è una firma RSA con SHA-256. L’emittente firma con una chiave privata e chiunque abbia la chiave pubblica può verificare. Altri servizi possono controllare i token senza poterli creare.
• ES256 è una firma ECDSA con la curva P-256 e SHA-256. Funziona come RS256 con chiavi e firme più piccole.

Usa HS256 quando un solo servizio emette e controlla i propri token. Usa RS256 o ES256 quando altri servizi devono controllare token che non hanno emesso.

Problemi che derivano dal fidarsi dell’header

L’header è scritto da chi invia il token, quindi il verificatore non deve lasciargli scegliere le regole.

1. alg: none. Un token senza firma può dichiarare "alg":"none". Alcune librerie in passato accettavano tali token saltando il controllo. Imposta gli algoritmi ammessi nel tuo codice, mai prendendoli dal token.
2. Confusione dell’algoritmo. Un server si aspetta RS256 e possiede una chiave pubblica. Un aggressore invia un token HS256 firmato usando quella chiave pubblica come segreto HMAC. Un verificatore che accetta qualunque algoritmo indicato dall’header lo accetta. Lega ogni chiave a un solo algoritmo.
3. Segreti deboli. L’aggressore ha header, payload e firma, quindi può provare segreti candidati offline. Un segreto corto o una parola comune cade rapidamente con una lista del genere. La RFC 7518 stabilisce che una chiave HS256 debba essere lunga almeno 256 bit e casuale.

Incollare un token di produzione in un sito

Un token valido e non scaduto funziona per chiunque lo possieda, finché non scade. Trattalo come una password. Prima di incollarlo in un sito, verifica se il sito lo invia a un server. Uno strumento che funziona interamente nella scheda del browser non ne ha bisogno. Puoi controllare una pagina osservando le sue richieste di rete negli strumenti per sviluppatori del browser.

I token di solito non possono essere revocati prima della scadenza, a meno che il server non tenga una lista. Se un token attivo viene divulgato, chiedi al servizio di revocare la sessione o di ruotare le chiavi. Quando puoi, usa per il debug un token dell’ambiente di test. Il decodificatore JWT legge le tre parti nella scheda del browser e non invia nulla di ciò che incolli.

Webhook: la stessa idea con un segreto condiviso

La maggior parte dei provider di webhook invia, in un header, un HMAC del corpo della richiesta, calcolato con un segreto condiviso con te. Il tuo ricevitore calcola lo stesso HMAC e confronta i due valori. Gli errori più comuni sono piccoli. Il JSON viene riformattato prima dell’hash, quindi cambiano i byte. Il segreto di test viene usato sul traffico reale. Oppure le firme vengono confrontate con il normale confronto di stringhe, che può far trapelare informazioni sui tempi. Usa un confronto a tempo costante.

Il test firma webhook calcola la firma a partire dal segreto e dal corpo che incolli, per GitHub, Stripe, Slack, Shopify o qualsiasi schema HMAC, così puoi vedere se i due valori coincidono.

Risposte rapide

Un JWT è cifrato?

No. Un JWT standard è firmato, e chiunque può leggerne header e payload. Solo la firma lo protegge dalle modifiche.

Che cosa succede se modifico il payload?

La firma smette di corrispondere, quindi un server che verifica rifiuta il token. Leggere i claim non controlla la firma, quindi il decodificatore mostrerà comunque la tua versione modificata.