Decodificare un JSON Web Token (JWT)

Cos'è un JWT (JSON Web Token)?

Un JSON Web Token, abbreviato in JWT (pronunciato "jot"), è un formato compatto definito dalla RFC 7519 che permette di trasportare una serie di rivendicazioni (claim) tra due parti. Il JWT, o token JWT, è oggi il formato dominante per veicolare un'identità autenticata in un'API HTTP. Un JWT si presenta come una stringa ASCII composta da tre segmenti separati da punti:

header.payload.signature

Ogni segmento è codificato in Base64URL, una variante di Base64 senza padding = e che sostituisce + con - e / con _ per poter circolare in un URL o un header HTTP senza escape aggiuntivo.

Anatomia di un JWT

Un json web token è composto da tre parti ben distinte, ognuna che gioca un ruolo preciso nel meccanismo di autenticazione:

1. Header

L'header è un oggetto JSON che descrive come il token è firmato. Contiene almeno:

• alg (algorithm): l'algoritmo di firma usato. Valori tipici: HS256, RS256, ES256, EdDSA.
• typ (type): il tipo del token, quasi sempre "JWT".
• kid (key ID): facoltativo, identifica quale chiave deve essere usata per verificare la firma. Pratico in presenza di un parco di chiavi in rotazione (JWKS).

2. Payload

Il payload contiene i claim, ossia le rivendicazioni che l'emettitore fa sull'utente o sulla sessione. La RFC 7519 definisce sette claim standard (registered claim):

• iss (issuer): chi ha emesso il token, per esempio "https://accounts.google.com".
• sub (subject): a chi appartiene il token, in pratica l'identificatore utente.
• aud (audience): a chi è destinato il token. Evita che un token emesso per l'API A sia accettato dall'API B.
• exp (expiration time): timestamp Unix dopo il quale il token non è più valido.
• nbf (not before): timestamp prima del quale il token non è ancora attivo.
• iat (issued at): timestamp di emissione del token.
• jti (JWT ID): identificatore unico del token, usato per la revoca e la prevenzione del replay.

A questi claim standard si aggiungono generalmente claim custom propri dell'applicazione (roles, scope, tenant_id, email, permissions...).

3. Signature

La firma è un digest crittografico calcolato su base64url(header) + "." + base64url(payload) con l'aiuto di una chiave. È lei che prova che nessuno ha modificato l'header né il payload dall'emissione. Gli algoritmi più comuni:

• HS256 / HS384 / HS512: firma simmetrica HMAC-SHA. Una chiave segreta condivisa tra l'emettitore e il verificatore. Semplice, ma inadatta non appena c'è più di un consumatore.
• RS256 / RS384 / RS512: firma asimmetrica RSA. L'emettitore firma con la sua chiave privata, qualsiasi consumatore verifica con la chiave pubblica corrispondente. Standard di fatto per OAuth2 e OpenID Connect.
• ES256 / ES384 / ES512: firma asimmetrica ECDSA. Stesse proprietà di RS256 ma con chiavi e firme molto più corte.
• EdDSA (Ed25519): firma asimmetrica moderna, rapida e compatta.

Ancora una volta: la firma protegge l'integrità, non la riservatezza. Il payload resta leggibile da chiunque possegga il token.

Perché decodificare un JWT?

L'operazione jwt token decode risponde a vari bisogni concreti per uno sviluppatore o un ingegnere della sicurezza:

• Debug di autenticazione: la vostra API restituisce un 401 o un 403, volete vedere cosa si trova realmente nel payload (sub, scope, roles, exp) piuttosto che indovinare.
• Verificare i claim: confermare che un token contenga effettivamente la rivendicazione attesa (per esempio tenant_id o permissions) prima di cercare altrove nella catena di autorizzazione.
• Leggere la scadenza: convertire il timestamp exp in data umana per confermare che un token sia effettivamente scaduto, o al contrario che dovrebbe essere ancora valido.
• Audit di sicurezza: assicurarsi che un servizio terzo non faccia trapelare informazioni sensibili nel payload (e-mail, identificatori interni, dati personali).
• Formazione e comprensione: vedere concretamente come si presenta un jsonwebtoken uscente da un provider OAuth (Google, Auth0, Keycloak, AWS Cognito) per capire la meccanica senza tuffarsi nella documentazione.
• Esplorazione di token pubblici: ispezionare un JWT trovato nei log, in un cookie o in uno scambio OAuth intercettabile.

Decoder vs Verifier: la distinzione critica

Le due operazioni sembrano vicine ma non hanno nulla a che fare in termini di garanzie di sicurezza:

• Decodificare un JWT consiste nel tagliare la stringa sui . e applicare un Base64URL inverso ai primi due segmenti. È una semplice lettura, alla portata di qualsiasi script di tre righe. Nessuna verifica di firma viene fatta.
• Verificare un JWT consiste nel ricalcolare la firma a partire da header, payload e una chiave, poi confrontare il risultato con la firma presente nel token. È ciò che garantisce che il token non sia stato falsificato.

Conclusione pratica: decodificare non vale fidarsi. Finché la firma non è stata verificata con la chiave giusta, il contenuto del payload può essere totalmente falso. Per la fase di fiducia, usate il nostro JWT Verifier.

Come usarlo

1. Recuperate il JWT da ispezionare, per esempio da un header Authorization: Bearer <jwt>, da un cookie di sessione, dal localStorage del browser, o da un log applicativo.
2. Incollate la stringa completa nel campo di input. I tre segmenti devono restare separati da punti.
3. Lo strumento mostra immediatamente l'header decodificato in JSON formattato, con l'algoritmo e il tipo.
4. Il payload viene poi decodificato e mostrato. Vedete tutti i claim standard e custom.
5. Lo strumento indica anche l'informazione di firma (algoritmo dichiarato, lunghezza), senza verificarla.
6. Per confermare che il token non sia stato falsificato, passate al nostro JWT Verifier con la chiave pubblica o il secret atteso.

Tutta la decodifica viene effettuata nel vostro browser in JavaScript: il vostro token non viene mai inviato ai nostri server.

JWT e sicurezza: le trappole da evitare

Alcune regole d'oro per usare bene i JWT in produzione:

• Verificare sempre la firma lato server prima di concedere il minimo diritto. Il nostro JWT Verifier illustra esattamente questa operazione.
• Preferire RS256 o ES256 a HS256 per le API pubbliche. La firma asimmetrica evita di condividere un secret tra l'emettitore e ogni consumatore.
• Sempre rispettare il claim exp. Un JWT senza scadenza o con una scadenza troppo lontana è una bomba a orologeria in caso di fuga.
• Validare iss e aud lato server, per evitare che un token legittimo emesso per un altro servizio sia accettato per errore.
• Rifiutare alg: "none" lato verifica. È una falla classica che permette a un attaccante di forgiare qualsiasi payload.
• Tenere le durate di vita corte (15 minuti per esempio) e accoppiare a un refresh token più lungo ma revocabile lato server.

Esempio di token JWT decodificato

Ecco un JWT tipico:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJuYW1lIjoiSm9obiIsImlhdCI6MTUxNjIzOTAyMn0.jrU9j8LZcRK2_BZjqXjU7lEpJbkqmXfTQIu9vT45j-I

Una volta decodificato, ecco il suo contenuto:

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

// Payload
{
  "sub": "123",
  "name": "John",
  "iat": 1516239022
}

// Signature (binaire, encodé en Base64URL)
HMACSHA256(
  base64url(header) + "." + base64url(payload),
  secret
)

Dove trovare un JWT da copiare?

In pratica, un JWT da decifrare (nel senso di decodificare) proviene il più delle volte da una di queste posizioni:

• Cookie HTTP: aprite gli strumenti di sviluppo (F12), scheda Application o Storage, poi Cookie. Individuate un cookie chiamato access_token, jwt, session o simili.
• localStorage / sessionStorage: stesso pannello, sezione Local Storage. Molte SPA vi memorizzano il loro token sotto una chiave token o auth.
• Header Authorization: scheda Network, selezionare una richiesta API, leggere l'header Authorization: Bearer <jwt>. Copiare solo la parte dopo Bearer .
• Log server: un JWT appare a volte nei log di un gateway o di un reverse proxy (da evitare in produzione, ma utile in debug).

Domande frequenti

Esempio di richiesta

curl -X POST https://cdrn.fr/api/v1/tools/jwt-decoder/execute \
  -H "Content-Type: application/json" \
  -d '{"token":"..."}'

Schema di input

Endpoint

• GET https://cdrn.fr/api/v1/tools - elenca tutti gli strumenti disponibili
• GET https://cdrn.fr/api/v1/tools/jwt-decoder - recupera lo schema di questo strumento
• POST https://cdrn.fr/api/v1/tools/jwt-decoder/execute - esegue questo strumento con un payload JSON