Anatomia di JWT: header, payload e firma

Un JSON Web Token (JWT) è un formato compatto di token sicuro per gli URL, definito nella RFC 7519. Codifica le claims (asserzioni relative a un soggetto) e una firma crittografica in un'unica stringa, consentendo un'autenticazione stateless.

Un JWT ha la forma: base64url(header).base64url(payload).base64url(signature). Il punto separa le parti. Header e payload sono leggibili (in base64url, non cifrati). Solo la signature è crittografica.

L'header è un oggetto JSON: {"alg":"HS256","typ":"JWT"}. alg specifica l'algoritmo di firma (HS256, RS256, ES256, none). typ è sempre "JWT". Tra gli header aggiuntivi è incluso kid (ID della chiave), utilizzato per selezionare la chiave.

Claims registrate standard: iss (emittente), sub (soggetto), aud (destinatario), exp (timestamp Unix di scadenza), nbf (non prima di), iat (emesso il), jti (ID del JWT per la revoca). Le claims personalizzate sono qualsiasi coppia chiave-valore aggiuntiva.

import base64, json token = "eyJ..." parts = token.split(".") header = json.loads(base64.urlsafe_b64decode(parts[0]+"==")) payload = json.loads(base64.urlsafe_b64decode(parts[1]+"==")) print(header, payload)

Per HS256: HMAC-SHA256(base64url(header)+"."+base64url(payload), secret). Il destinatario ricalcola questo valore e lo confronta con la parte signature. Se corrispondono e il token non è scaduto, il token è valido.

Per RS256: la chiave privata firma la stringa header.payload utilizzando RSA-SHA256. Qualsiasi soggetto in possesso della chiave pubblica può verificare la firma senza la chiave privata. Le chiavi pubbliche vengono distribuite tramite endpoint JWKS (JSON Web Key Set), ad esempio /.well-known/jwks.json.

Base64url sostituisce + con - e / con _, ed elimina il padding =. In questo modo i JWT possono essere utilizzati negli URL, nelle intestazioni HTTP e nei cookie senza codifica percentuale. I byte originali non sono comunque cifrati: sono solo codificati.

Il payload di un JWT è visibile a chiunque lo decodifichi da base64url. Non inserisca mai segreti (password, numeri di previdenza sociale) nel payload di un JWT, a meno che non utilizzi JWE (JSON Web Encryption) con l'algoritmo "enc" per la cifratura effettiva.

Imposti exp su una durata breve (15-60 minuti per i token di accesso). I JWT di lunga durata accumulano rischi: se vengono sottratti, restano validi fino alla scadenza. Utilizzi refresh token (conservati in modo sicuro) per emettere nuovi token di accesso di breve durata.

I provider di autenticazione (Auth0, Keycloak, Google) pubblicano un URL JWKS. Il verificatore recupera le chiavi pubbliche in base a kid, le mette in cache e verifica le firme senza contattare l'emittente a ogni richiesta. La rotazione delle chiavi aggiorna l'endpoint JWKS.

Un JWT è composto da tre parti JSON codificate in base64url: header (algoritmo), payload (claims) e signature. Il payload è leggibile, non cifrato. Prossimo argomento: scelta tra HS256 e RS256.