Claim

Un claim è una coppia nome/valore nel payload di un JWT che afferma qualcosa sul soggetto del token. I claim sono proprietà JSON; il payload è un oggetto JSON che li contiene. Claim standard definiti nell’RFC 7519 §4:

• iss — Issuer: chi ha creato il token.
• sub — Subject: a chi si riferisce il token (tipicamente un ID utente).
• aud — Audience: a chi è destinato il token. Può essere una stringa o un array.
• exp — Expiry: secondi Unix dopo i quali il token deve essere rifiutato.
• iat — Issued At: secondi Unix in cui il token è stato creato.
• nbf — Not Before: secondi Unix prima dei quali il token non è valido.
• jti — JWT ID: un identificatore univoco per il tracciamento della revoca.

Oltre all’insieme standard, le applicazioni aggiungono i propri claim: role, email, tenant_id, permissions, ecc. L’RFC 7519 non limita l’aspetto dei claim personalizzati, sebbene l’IANA mantenga un registro di nomi noti per prevenire collisioni.

Tre classi di claim da distinguere: registrati (i sette precedenti, gestiti dall’IANA), pubblici (registrati presso l’IANA o con namespace sotto un URI per evitare collisioni) e privati (concordati tra emittente e consumatore; nessun namespace).

Decodifica e ispeziona ogni claim in un JWT con il nostro decoder JWT. Mostra separatamente i claim standard e visualizza il tempo alla scadenza rispetto all’ora corrente del tuo computer.

Namespacing dei claim personalizzati — la pratica standard: quando un’applicazione aggiunge claim personalizzati che potrebbero essere incorporati in un token condiviso tra vendor, prefissali con un URI di tua proprietà. Auth0 usa https://yourdomain.com/claims/role; AWS Cognito usa cognito:groups. I nomi semplici come role o permissions sono comodi ma rischiano di collidere con futuri claim registrati dall’IANA e con le convenzioni di altri vendor. OpenID Connect specifica alcuni nomi convenzionali (email, name, given_name, family_name, picture, locale) che hanno significati stabili tra i provider di identità — questi sono sicuri da usare così come sono in qualsiasi flusso conforme a OIDC. Riferimento: Registro IANA dei claim JSON Web Token.

Esempio pratico: validare exp e nbf

Considera un payload JWT {"sub":"42","iat":1716220800,"exp":1716224400,"nbf":1716220800}. Il token è stato emesso al timestamp Unix 1716220800 (2024-05-20 16:00:00 UTC), è valido a partire da subito e scade a 1716224400 (2024-05-20 17:00:00 UTC) — una durata di un’ora. Un verificatore corretto legge l’ora Unix corrente, rifiuta il token se now ≥ exp (con un piccolo margine opzionale, tipicamente 30-60 secondi, per assorbire lo sfasamento degli orologi tra i servizi) e rifiuta se now < nbf. L’RFC 7519 §4.1.4 impone che l’elaborazione di exp “DEVE” tenere conto dello sfasamento degli orologi ma lascia la tolleranza all’implementatore. Un margine di 60 secondi è il default de facto del settore; jose, jsonwebtoken e pyjwt usano tutti finestre configurabili da 0 a 60 secondi.

Perché è importante: le implicazioni per la sicurezza

La maggior parte degli incidenti di sicurezza JWT risale a omissioni nella validazione dei claim, non a fallimenti crittografici. L’advisory Auth0 CVE-2018-0114 del 2018 ha documentato librerie che verificavano la firma ma saltavano exp, consentendo la ripetizione di token rubati a tempo indeterminato. Diversi framework sono stati forniti con verificatori predefiniti che ignorano aud, consentendo a un token emesso per un servizio di essere accettato da un altro nello stesso dominio di fiducia. Best practice: verifica sempre l’insieme completo dei claim standard applicabili (iss, aud, exp, nbf, più firma e allow-list degli algoritmi) — ogni libreria li espone come opzioni del costruttore o della chiamata di verifica, e il costo per abilitarli è essenzialmente zero. Riferimento: RFC 8725 — Migliori pratiche correnti per JSON Web Token.