Verificarea semnăturii unui JSON Web Token (JWT)

De ce să verifici semnătura unui JWT?

Un JSON Web Token (JWT) se descompune în trei părți separate de puncte: header.payload.signature. A decoda un JWT constă simplu în a citi primele două părți (care sunt Base64URL). Oricine poate face acest lucru, și oricine poate fabrica un JWT cu payload-ul ales. Ceea ce face un JWT demn de încredere este doar semnătura: fără verificare, a accepta un JWT echivalează cu a lăsa să intre la tine orice persoană care pretinde că este cineva, fără să ceri o piesă de identitate.

Acest instrument verifică semnătura a unui JWT plecând de la o cheie. Nu se mulțumește să decodeze: recalculează semnătura plecând de la header, payload și cheia ta, apoi o compară cu semnătura token-ului. Dacă cele două concordă, token-ul este autentic. Altfel, a fost forjat, modificat, sau semnat cu altă cheie.

Verificarea este piatra de temelie a oricărei arhitecturi care utilizează JWT-uri pentru autentificare sau autorizare: fără semnătură validă, payload-ul poate minți. Un atacator care ar modifica "role":"user" în "role":"admin" nu ar avea nicio dificultate să o facă dacă serverul ar verifica doar formatul token-ului și nu semnătura sa.

Algoritmi curenți

Specificația JWT (RFC 7518, JSON Web Algorithms) definește mai multe familii de algoritmi. Iată cele mai utilizate în producție:

• HMAC (HS256, HS384, HS512): semnătură simetrică pe bază de HMAC-SHA. Aceeași cheie secretă servește la semnare și la verificare. Simplu de pus în loc, performant, dar orice parte capabilă să verifice token-ul este de asemenea capabilă să emită. Adaptat scenariilor unde emitentul și verificatorul sunt aceeași echipă sau același serviciu.
• RSA (RS256, RS384, RS512): semnătură asimetrică. Cheia privată semnează, cheia publică verifică. Ideal când emitentul și verificatorii sunt entități distincte (OAuth2, OpenID Connect, federație de identitate). Este algoritmul privilegiat de majoritatea furnizorilor de identitate publici.
• ECDSA (ES256, ES384): semnătură asimetrică pe curbe eliptice. Aceeași logică ca RSA (cheie privată pentru a semna, cheie publică pentru a verifica) dar cu chei și semnături mai compacte pentru un nivel de securitate echivalent. Din ce în ce mai răspândit în arhitecturile moderne.

Cum să furnizezi cheia

Formatul cheii așteptate depinde de algoritmul declarat în header-ul JWT-ului:

• HS256, HS384, HS512: cheia este un șir secret (string). Este secretul partajat cu emitentul, adesea stocat într-o variabilă de mediu precum JWT_SECRET. Nicio punere în formă particulară, doar valoarea brută.
• RS256, RS384, RS512: cheia este o cheie publică RSA în format PEM, care începe cu -----BEGIN PUBLIC KEY----- și se termină cu -----END PUBLIC KEY-----. Păstrează returnurile la linie ca atare, altfel OpenSSL refuză să o parseze.
• ES256, ES384: cheia este o cheie publică ECDSA în format PEM, pe curba corespunzătoare (P-256 pentru ES256, P-384 pentru ES384).

Exemplu de cheie publică RSA așteptată

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxe...
...vQIDAQAB
-----END PUBLIC KEY-----

Cum funcționează verificarea?

Serverul nostru reproduce exact operația pe care a făcut-o emitentul:

1. Separă JWT-ul în header, payload și semnătură.
2. Concatenează base64url(header) + "." + base64url(payload).
3. Pentru HMAC, calculează un HMAC-SHA-256/384/512 cu cheia ta secretă, apoi compară cu semnătura primită prin hash_equals (comparație în timp constant pentru a evita atacurile temporale).
4. Pentru RSA, apelează openssl_verify cu cheia ta publică în format PEM.

Cazuri de utilizare

• Debug de autentificare API: primești un 401, verifici dacă token-ul tău este într-adevăr semnat cu cheia așteptată.
• Validare a unui token primit de la un furnizor: un partener (Auth0, Keycloak, Cognito, Okta) îți trimite JWT-uri semnate în RS256; vrei să confirmi că provin într-adevăr de la el cu cheia sa publică.
• Audit de securitate: a verifica dacă un serviciu terț își semnează corect token-urile cu un algoritm robust, și nu în HS256 cu un secret slab.
• Teste manuale: a verifica dacă un JWT generat de codul tău trece bine verificarea cu cheia publică furnizată.
• Verificare rapidă a unui token primit: în timpul integrării unui SSO sau a unui API partener, a verifica în câteva secunde că lanțul semnătură/cheie funcționează înainte de a scrie cea mai mică linie de cod.

Cum să utilizezi instrumentul

1. Lipește JWT-ul complet (cele trei părți separate de puncte).
2. Indică cheia adaptată algoritmului header-ului:
   • Pentru HS256, HS384 sau HS512, cheia este șirul secret partajat cu emitentul. Este un șir liber, adesea stocat într-o variabilă de mediu precum JWT_SECRET.
   • Pentru RS256, RS384 sau RS512, cheia este cheia publică în format PEM, care începe cu -----BEGIN PUBLIC KEY----- și se termină cu -----END PUBLIC KEY-----.
3. Lansează verificarea. Instrumentul afișează statutul (valid sau invalid) și payload-ul decodat.

Capcane curente de evitat

• Algoritmul "none": specificația autorizează alg: none, care înseamnă "fără semnătură". O vulnerabilitate clasică constă în a fabrica un token cu acest header sperând ca serverul să-l accepte. Instrumentul nostru respinge sistematic token-urile cu alg: none.
• Confuzie HMAC vs RSA (algorithm confusion): un atacator schimbă algoritmul RS256 în HS256 și semnează payload-ul cu cheia publică RSA utilizată ca secret HMAC. Dacă serverul nu controlează algoritmul, acceptă token-ul. Întotdeauna blochează algoritmul așteptat pe partea serverului.
• Secrete HMAC în clar în cod: un secret commitat într-un depozit Git face toată încrederea token-urilor caducă. Stochează secretele în variabile de mediu sau într-un seif aplicativ.
• Cheie publică vs cheie privată: pentru a verifica un JWT semnat în RSA sau ECDSA, se furnizează cheia publică, niciodată privata. Privata servește doar la semnare și nu trebuie niciodată să iasă de la emitent.
• Expirare ignorată: o semnătură validă pe un token expirat nu trebuie niciodată să fie acceptată. Gândește-te să verifici exp și nbf.
• Audiență necontrolată: un token destinat API-ului A nu ar trebui să fie acceptat de API-ul B. Verifică claim-ul aud.

Claim-uri temporale: exp și nbf

Dincolo de semnătură, un JWT valid trebuie să respecte și constrângerile sale temporale:

• exp (expirare): token-ul nu mai este valid după această dată.
• nbf (not before): token-ul nu este încă valid înainte de această dată.

Instrumentul nostru semnalează explicit când un token este expirat sau nu încă valid, chiar dacă semnătura sa este corectă. Este important: o semnătură validă pe un token expirat nu trebuie niciodată acceptată în producție.

Diferența cu JWT decoder-ul nostru

JWT decoder-ul nostru se mulțumește să decodeze părțile header și payload pentru a le face lizibile. Nu efectuează nicio verificare de semnătură și nu cere o cheie. Utilizează-l pentru a inspecta rapid conținutul unui token. Utilizează JWT verifier-ul (această pagină) imediat ce ai nevoie să dovedești că un token este autentic. Pentru a fabrica un JWT semnat în scop de test, utilizează JWT builder-ul nostru.

Întrebări frecvente

Exemplu de cerere

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

Schema de intrare

Puncte de acces

• GET https://cdrn.fr/api/v1/tools - listează toate instrumentele disponibile
• GET https://cdrn.fr/api/v1/tools/jwt-verifier - obține schema acestui instrument
• POST https://cdrn.fr/api/v1/tools/jwt-verifier/execute - execută acest instrument cu un payload JSON