Creare un JSON Web Token (JWT) firmato

Cos'è JWT Builder?

JWT Builder è uno strumento online che produce un JSON Web Token firmato (JWT) a partire da un payload JSON e un secret HMAC. È rivolto agli sviluppatori che hanno bisogno di generare rapidamente un token di test per verificare il comportamento di un'API, simulare una sessione autenticata in Postman, o riprodurre un bug legato alla scadenza o all'ambito di un token.

A differenza del nostro JWT decoder, che si limita a leggere un token esistente, JWT Builder fabbrica un token completo: costruisce l'header, codifica il payload, calcola la firma HMAC e assembla il tutto nel formato compatto header.payload.signature atteso da tutte le librerie JWT del mercato.

Perché generare un JWT?

Un builder di JWT non ha vocazione a emettere token di produzione. È prima di tutto uno strumento di sviluppo e test. Ecco gli scenari più comuni:

• Test di integrazione: produrre JWT prevedibili per pilotare test E2E che colpiscono endpoint protetti senza dipendere dal vero provider di identità.
• Mock di API: sostituire temporaneamente una chiamata all'IdP con un JWT firmato localmente con lo stesso secret di test.
• Sviluppo locale: connettersi al proprio backend generando a mano un token che contenga i claim voluti, senza dover passare per tutto il flow OAuth2.
• Demo: illustrare un percorso di autenticazione o un workflow basato su permessi senza avere un IdP reale a disposizione.
• Riproduzione di bug: forgiare un token scaduto, un token con un aud errato, un token senza certi claim, per testare i percorsi di errore della vostra API.
• Debugging di un parser custom: iniettare JWT specialmente costruiti per testare un parser fatto in casa.

Composizione di un JWT

Un JWT firmato è composto da tre segmenti separati da un punto, ognuno codificato in Base64URL (variante di Base64 senza padding e con -/_ al posto di +//):

• Header: un oggetto JSON che descrive l'algoritmo di firma e il tipo del token, per esempio {"alg":"HS256","typ":"JWT"}. JWT Builder lo genera automaticamente a partire dall'algoritmo che scegliete.
• Payload: un oggetto JSON arbitrario che contiene i claim del token (soggetto, permessi, date di scadenza). È la parte che fornite voi.
• Signature: un HMAC-SHA calcolato sulla concatenazione base64url(header) + "." + base64url(payload) con la vostra chiave segreta. È lei che garantisce l'integrità del token.

Casi d'uso in dettaglio

• API mock per test E2E: la vostra suite Cypress o Playwright deve chiamare un'API che richiede un Authorization: Bearer .... Piuttosto che orchestrare un login completo a ogni test, si firma un JWT al volo con il secret condiviso e lo si inietta nell'header.
• Demo di SSO: presentare un percorso di autenticazione federata senza dipendere da un IdP online.
• Fixture di test: generare un JWT deterministico a partire da un payload conosciuto per servire come fixture stabile in test unitari.
• Diagnosi di un parser custom: testare un parser JWT fatto in casa con token volutamente minimali o volutamente strani (claim mancanti, tipi inattesi).
• Apprendimento: capire concretamente come si costruisce un JWT, modificando il payload e osservando la firma cambiare.

Algoritmi supportati: HS256, HS384, HS512

Il nostro strumento supporta i tre algoritmi HMAC standard della specifica JWT (RFC 7519):

• HS256: HMAC con SHA-256. Firma di 32 byte. Il più usato in pratica, buon compromesso tra velocità e solidità crittografica. Raccomandato per default.
• HS384: HMAC con SHA-384. Firma di 48 byte. Adatto ai contesti che richiedono un margine di sicurezza superiore.
• HS512: HMAC con SHA-512. Firma di 64 byte. Il più robusto, al prezzo di un token leggermente più voluminoso.

HMAC o RSA?

Gli algoritmi HS* sono simmetrici: la stessa chiave serve a firmare e a verificare. È semplice e rapido, ma significa che ogni servizio capace di verificare un token è anche capace di emetterlo. Se avete bisogno di separare questi due ruoli (un solo emettitore, più consumatori), rivolgetevi agli algoritmi RS256/RS384/RS512 (RSA, asimmetrici), che potete verificare con il nostro JWT verifier.

Sicurezza: proteggere il vostro secret

La sicurezza di un JWT firmato in HMAC poggia interamente sulla riservatezza del secret. Alcune regole di base:

• Usate un secret lungo e casuale. La RFC 7518 raccomanda almeno la dimensione dell'output dell'algoritmo (32 byte per HS256, 48 per HS384, 64 per HS512). Una password umana come azerty123 è banalmente attaccabile per forza bruta offline.
• Non firmate mai un JWT lato client. Il secret si ritroverebbe nel codice JavaScript distribuito al browser, esposto a ogni utente. La firma deve sempre restare lato server.
• Memorizzate il secret in una variabile d'ambiente (es. JWT_SECRET), mai in un repository Git. Pensate a usare un vault come HashiCorp Vault, AWS Secrets Manager o i Symfony Secrets a seconda del vostro stack.
• Ruotate il secret regolarmente (key rotation), soprattutto dopo ogni incidente o partenza di una persona che ha avuto accesso alla configurazione.
• JWT Builder è destinato a test e apprendimento. Per la produzione, usate la libreria JWT del vostro framework (lcobucci/jwt, firebase/php-jwt, jose-php).

Buone pratiche di claim

Il payload è un oggetto JSON libero, ma la RFC 7519 definisce un insieme di registered claim che le librerie JWT sanno interpretare. Includere i claim giusti rende il vostro token portabile ed evita bug sottili:

• iss (issuer): identificatore dell'emettitore, per esempio "https://api.example.com".
• sub (subject): identificatore della persona o entità interessata, spesso l'ID utente.
• aud (audience): a chi è destinato il token, per impedire il riutilizzo di un token su un'altra API.
• exp (expiration time): timestamp Unix dopo il quale il token non è più valido. Sempre includere, anche per un token di test: un token senza scadenza è una cattiva abitudine difficile da correggere in seguito.
• nbf (not before): timestamp prima del quale il token non è ancora valido. Utile per pre-emettere un token attivabile in seguito.
• iat (issued at): timestamp di emissione, utile per loggare e revocare.
• jti (JWT ID): identificatore unico del token, indispensabile per l'idempotenza e per implementare una lista di revoca.

Esempio di payload tipico

{
  "iss": "https://api.example.com",
  "sub": "user-12345",
  "aud": "mobile-app",
  "iat": 1714723200,
  "exp": 1714726800,
  "jti": "9f2d6b1e-2c4a-4f8a-9c3a-87a2b8a4b7e1",
  "scope": "read:profile write:profile"
}

Come usare lo strumento

1. Inserite il payload come JSON valido. È un oggetto, quindi comincia con { e termina con }.
2. Indicate il secret HMAC. Scegliete una stringa lunga e casuale per i token di produzione.
3. Selezionate l'algoritmo: HS256 per default, HS384 o HS512 secondo le vostre esigenze.
4. Cliccate su crea. Il JWT firmato appare, pronto da incollare in un header Authorization: Bearer ....
5. Potete poi verificare il token con lo stesso secret per confermare la coerenza del round-trip, o decodificarlo per rileggere il suo contenuto.

Domande frequenti

Esempio di richiesta

curl -X POST https://cdrn.fr/api/v1/tools/jwt-builder/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"...","secret":"...","algorithm":"HS256"}'

Schema di input

Endpoint

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