JWT spiegato: struttura, claim e come decodificarne uno

Se hai lavorato con un'API web moderna, hai incontrato i JWT — quelle lunghe stringhe incomprensibili con due punti che compaiono nelle risposte di login e negli header Authorization. Sembrano opachi, ma sono sorprendentemente leggibili una volta che ne conosci la struttura. Questa guida spiega cos'è un JSON Web Token, cosa contiene, come funziona la firma e gli errori di sicurezza da evitare.

A cosa serve un JWT

Un JSON Web Token (JWT) è un modo compatto e autocontenuto di trasportare un insieme di claim — affermazioni come «questo è l'utente 42 e ha effettuato l'accesso alle 10:05». Il suo uso principale è l'autenticazione: dopo il login, un server emette un JWT, la tua app lo rimanda a ogni richiesta, e il server si fida di esso invece di cercarti in un archivio di sessione ogni volta. Poiché il token porta l'informazione in sé, si dice senza stato (stateless).

Le tre parti

Ogni JWT è composto da tre sezioni codificate in Base64URL unite da punti: header.payload.signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3x9kQ...
└──── header ────┘ └── payload ──┘ └ signature ┘

1. Header

Metadati sul token — l'algoritmo di firma (alg, es. HS256) e il tipo (typ: JWT). Decodificato, è solo un piccolo JSON:

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

2. Payload

I claim — i dati veri e propri. Alcuni nomi sono standardizzati (detti claim registrati):

• sub — soggetto (subject), di solito l'ID utente.
• iss — emittente (issuer), chi ha creato il token.
• aud — destinatario (audience), a chi è destinato.
• exp — ora di scadenza (un timestamp Unix).
• iat — ora di emissione (un timestamp Unix).

Quei valori exp e iat sono secondi dal 1970 — se devi leggerli come date reali, un convertitore di timestamp li trasforma in orari leggibili.

3. Firma (Signature)

La firma è ciò che rende il token affidabile. L'emittente prende header e payload e, usando una chiave segreta, produce una firma crittografica. Chiunque abbia la chiave può verificare che header e payload non siano stati alterati — cambia un solo carattere nel payload e la firma non corrisponde più.

La cosa più importante da capire

Un JWT è firmato, non cifrato. Header e payload sono solo codificati in Base64URL, il che significa che chiunque può decodificarli e leggerli — nessuna chiave necessaria. La firma impedisce la manomissione, non la lettura.

La conseguenza pratica: non mettere mai segreti nel payload di un JWT. Niente password, numeri di carta o dati privati — considera il payload pubblico. Puoi confermarlo tu stesso incollando qualsiasi token nel nostro decodificatore JWT, che legge header e claim all'istante, interamente nel tuo browser (il token non lascia mai il dispositivo). Sotto è solo decodifica Base64 — il decodificatore ti risparmia solo i passaggi.

Verificare vs. decodificare

Sono due azioni diverse, e confonderle è un vero bug di sicurezza. Decodificare legge il payload — chiunque può farlo e non prova nulla. Verificare controlla la firma con la chiave e conferma che il token sia autentico e inalterato. Un server deve verificare ogni token prima di fidarsene; la sola decodifica non è autenticazione.

Trappole comuni

• Fidarsi di un token non verificato — controlla sempre la firma lato server prima di agire in base ai claim.
• Ignorare la scadenza — rispetta exp; un token scaduto va rifiutato.
• Memorizzare dati sensibili nel payload — è leggibile da chiunque.
• La trappola `alg: none` — alcune librerie un tempo accettavano token che dichiaravano «nessuna firma». Rifiutali e fissa l'algoritmo atteso.

Capisci questo e i JWT passano da stringhe intimidatorie a un formato semplice e trasparente: claim leggibili, protetti da una firma che devi verificare prima di fidarti.