Decodificatore JWT

Che cos'è un JSON Web Token (JWT)

Un JWT (RFC 7519) è un’affermazione firmata che un emittente fa su un soggetto, codificata in modo da sopravvivere a un URL o a un’intestazione HTTP. Le tre parti separate dai punti hanno ciascuna un compito.

• L’intestazione indica algoritmo e tipo: {"alg":"HS256","typ":"JWT"}. Può contenere anche kid, l’identificativo della chiave, che dice a chi verifica quale tra più chiavi pubbliche usare.
• Il payload i claim. Quelli registrati hanno un significato condiviso: iss (emittente), sub (soggetto, di solito l’id utente), aud (destinatario), exp (scadenza), iat (emesso il), nbf (non prima di), jti (identificativo univoco). Tutto il resto è quello che l’emittente ha deciso di metterci: ruoli, tenant, email.
• La firma le prime due parti firmate con la chiave. È ciò che rende il token affidabile, ed è l’unica parte che questo strumento, di proposito, non tocca.

Decodificare non è verificare

È la distinzione che conta, ed è quella che causa incidenti di sicurezza veri. Decodificare un JWT significa leggerlo. Verificare un JWT significa dimostrare che l’emittente l’ha davvero firmato e che nessuno ha cambiato un claim per strada. Sono operazioni diverse, e solo la seconda rende il contenuto affidabile.

Chiunque abbia il token può decodificarlo: è esattamente quello che stai facendo in questa pagina. Quindi il payload di un JWT non è il posto in cui mettere qualcosa che non vuoi far leggere: è firmato, non cifrato. Se i claim devono essere illeggibili a chi porta il token, ti serve JWE, oppure un token opaco il cui significato vive solo nel tuo database.

E non lasciare mai che un token non verificato decida qualcosa. L’attacco classico è il token con «alg» a «none»: chi attacca toglie la firma e riscrive i claim, e un server che decodifica senza verificare lo accetta come amministratore. A una libreria che verifica va detto quali algoritmi può accettare, invece di fidarsi dell’intestazione.

Rispondere alle domande con cui sei arrivato

• «Questo token è scaduto?» exp è mostrato come data e confrontato con il tuo orologio. Ricorda che l’orologio è il tuo: qualche secondo di scarto tra il tuo computer e il server è normale, e quasi tutte le librerie prevedono una piccola tolleranza proprio per questo.
• «Di quale account si tratta?» sub è il soggetto, l’identificativo stabile. Il nome visualizzato accanto, se c’è, è una comodità e può cambiare; sub no.
• «Perché il gateway lo rifiuta?» controlla aud rispetto a quello che si aspetta l’API, iss rispetto all’emittente di cui si fida, e nbf, che rende un token non valido fino a un istante che potrebbe non essere ancora arrivato.
• «Quale chiave l’ha firmato?» il kid nell’intestazione, confrontato con le chiavi pubblicate sull’endpoint JWKS dell’emittente. Una chiave ruotata con una cache vecchia è una causa frequente di rifiuti improvvisi e di massa.

Quando un token non si decodifica

• Non è in tre parti conta i punti: un JWT ne ha esattamente due. Un punto solo di solito vuol dire che la firma è stata tagliata; quattro, che sono stati incollati due token.
• Un carattere fuori dall’alfabeto Base64 quasi sempre una copia incompleta che ha preso anche un apice, una virgola o dei puntini di sospensione dal testo intorno. Controlla prima i due estremi della stringa.
• Si decodifica ma non è JSON allora probabilmente non è affatto un JWT. Anche i token di sessione opachi e le chiavi API sono spesso in Base64 e non hanno struttura leggibile: il loro significato vive nel database di chi li emette.
• Il prefisso Bearer copiato dritto da un’intestazione Authorization. Qui viene tolto in automatico, ma una libreria a cui passi l’intera intestazione non lo farà per te.