Ghid pentru Decodor JWT
Cum este construit un JSON Web Token, ce arată Decodor JWT despre revendicări și expirare, cum funcționează verificarea semnăturii și ce greșeli să evitați.
Cum este construit un JWT
Un JSON Web Token (RFC 7519) este un mod compact de a transporta revendicări între sisteme, precum un identificator de utilizator și un moment de expirare. Este alcătuit din trei părți separate prin puncte: un antet care numește algoritmul de semnare, un payload cu revendicările și o semnătură calculată peste primele două părți. Fiecare parte este codificată base64url. Șirul rezultat este suficient de scurt pentru a încăpea într-un antet HTTP, într-un cookie sau într-un parametru de interogare, ceea ce explică de ce este atât de răspândit în API-uri și în sistemele de autentificare.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 header: {"alg":"HS256","typ":"JWT"}
.eyJzdWIiOiIxMjMiLCJleHAiOjE3NTc5MDAwMDB9 payload: {"sub":"123","exp":1757900000}
.3q2-7wrBx... signature: HMAC-SHA256 over header.payloadOricine poate decoda antetul și payload-ul; base64url este o codificare, nu o criptare. Semnătura este cea care face tokenul demn de încredere: numai o parte care deține cheia potrivită o poate produce, iar orice modificare a antetului sau a payload-ului o invalidează. Există și tokenuri criptate (JWE), însă marea majoritate a tokenurilor care circulă prin API-uri și prin sistemele de autentificare sunt doar semnate. De aceea nu tratați niciun câmp din interiorul unui token ca fiind secret; oricine ajunge la token îl citește exact așa cum îl citește această pagină.
Cum folosiți Decodor JWT
- Deschideți Decodor JWT și lipiți un token. Este decodat în browserul dumneavoastră pe măsură ce scrieți.
- Citiți antetul și payload-ul ca JSON formatat, împreună cu notele despre algoritm, expirare și revendicări.
- Ca să verificați semnătura, introduceți secretul HMAC (bifați base64url dacă secretul este păstrat în acea formă) sau lipiți o cheie publică în format PEM ori JWK.
- Apăsați Verifică semnătura și citiți rezultatul.
Tratați tokenurile reale ca pe niște parole
Revendicări înregistrate
| Revendicare | Nume | Semnificație |
|---|---|---|
iss | Emitent | Cine a creat și a semnat tokenul |
sub | Subiect | Despre cine sau despre ce este tokenul, adesea un identificator de utilizator |
aud | Audiență | Cui îi este destinat tokenul; destinatarii trebuie să verifice acest lucru |
exp | Moment de expirare | Secunde de la 1970-01-01 UTC, după care tokenul trebuie respins |
nbf | Nu înainte de | Momentul înaintea căruia tokenul trebuie respins |
iat | Emis la | Când a fost creat tokenul |
jti | Identificator JWT | Identificator unic, util pentru listele de revocare și protecția la reluare |
{
"iss": "https://auth.example.com",
"sub": "user-8812",
"aud": "https://api.example.com",
"iat": 1789462800,
"exp": 1789463700,
"scope": "orders:read"
}Revendicările de timp sunt marcaje Unix exprimate în secunde, nu în milisecunde. Decodorul le transformă în durate lizibile, precum „a expirat acum 3 ore” sau „mai este valid 14 minute”, folosind ceasul dispozitivului dumneavoastră. Dacă ceasul dispozitivului este greșit, și acele durate sunt greșite. Acestea sunt cele două cauze obișnuite pentru care un token proaspăt emis pare expirat: un ceas care a luat-o razna sau un exp scris în milisecunde. Câmpurile care nu apar în tabel, precum scope, role sau email, sunt revendicări private, iar înțelesul lor este stabilit de sistemul care emite tokenul, nu de standard.
Despre ce avertizează decodorul
| Notă | Severitate | Motiv |
|---|---|---|
| alg are valoarea „none” | Critic | Tokenul nu este semnat; acceptarea lui permite oricui să inventeze revendicări |
| Antetul nu are alg | Critic | Bibliotecile ar trebui să respingă tokenurile fără algoritm |
| Partea de semnătură este goală | Critic | Un algoritm semnat nu poate fi valid fără semnătură |
| A expirat acum … (exp) | Avertisment | Serverele trebuie să respingă tokenul |
| Lipsește revendicarea exp | Avertisment | Tokenul nu expiră niciodată, dacă serverul nu impune o durată de viață |
| Nu este valid încă (nbf) | Avertisment | Tokenul este folosit înainte de momentul său de start sau ceasurile diferă |
| iat este în viitor | Avertisment | Ceasul emitentului este probabil greșit |
| Payload-ul conține câmpuri de tip parolă sau secret | Avertisment | Payload-ul poate fi citit de oricine deține tokenul |
Verificarea semnăturilor
| alg | Tip | Cheia necesară pentru verificare |
|---|---|---|
HS256, HS384, HS512 | HMAC cu SHA-2 | Secretul partajat |
RS256, RS384, RS512 | RSA PKCS#1 v1.5 | Cheie publică RSA (PEM sau JWK) |
PS256, PS384, PS512 | RSA-PSS | Cheie publică RSA (PEM sau JWK) |
ES256, ES384, ES512 | ECDSA | Cheie publică EC pe curba potrivită (PEM sau JWK) |
La algoritmii HMAC, același secret semnează și verifică, așa că oricine poate verifica poate și să creeze tokenuri. Algoritmii asimetrici separă cele două roluri: emitentul păstrează cheia privată și publică cheia publică, adesea sub forma unui document JWKS, astfel încât orice serviciu poate verifica fără a putea emite. Pentru sistemele în care multe servicii consumă tokenuri, cheile asimetrice sunt varianta de proiectare mai sigură. Ele ușurează și rotirea cheilor, pentru că singurul lucru care trebuie protejat este partea privată de la emitent.
Verificarea folosește implementarea WebCrypto a browserului. O verificare reușită dovedește doar că tokenul a fost semnat cu cheia potrivită; ea nu verifică iss, aud sau dacă tokenul a fost revocat, lucruri care rămân în sarcina serverului care primește tokenul. De aceea un rezultat pozitiv nu înseamnă, de unul singur, că tokenul este valid pentru API-ul dumneavoastră. Instrumentul nici nu descarcă o adresă JWKS și nici nu rezolvă valoarea kid din antet în locul dumneavoastră; cheia potrivită o lipiți chiar dumneavoastră.
Greșeli frecvente cu JWT
- Acceptarea algoritmului din token. Configurați algoritmii așteptați pe server; nu lăsați niciodată antetul
algsă aleagă, pentru că exact așa funcționeazănoneși atacurile prin confuzie de chei. - Secrete HMAC slabe. Secretele scurte sau ghicibile pot fi sparte offline, prin forță brută, pornind de la un singur token. Folosiți cel puțin tot atâția octeți aleatori câți are ieșirea funcției hash, de exemplu 32 de octeți pentru HS256.
- Fără expirare sau cu durate de viață foarte lungi. Tokenurile nu pot fi revocate ușor, așa că păstrați tokenurile de acces de scurtă durată și folosiți tokenuri de reîmprospătare pentru sesiuni lungi.
- Date sensibile în payload. Orice se află în payload poate fi citit de cine deține tokenul, inclusiv de extensiile de browser, de proxy-uri și de jurnale.
- Neverificarea revendicării aud. Un token emis pentru un serviciu nu ar trebui acceptat de altul, doar pentru că se întâmplă să aibă încredere în același emitent.
- Stocarea tokenurilor acolo unde le pot citi scripturile. Tokenurile din
localStoragesunt expuse oricărui XSS; pentru sesiunile din browser, cookie-urile HttpOnly evită acest lucru.
Ghidul CSP tratează limitarea injectării de scripturi, care protejează tokenurile păstrate în browser. Pentru a inspecta mai în detaliu JSON-ul din interiorul tokenurilor, Instrumente JSON poate afișa ordonat payload-urile decodate. Ambele instrumente prelucrează datele introduse numai în browserul dumneavoastră, așa că tokenul la care lucrați nu părăsește pagina. Dacă trebuie să produceți un secret sau o pereche de chei, luați octeții aleatori de la generatorul sigur al platformei și păstrați rezultatul într-un manager de secrete.
Întrebări frecvente
Este sigur să lipesc aici un token?
Tokenul și cheile sunt prelucrate numai în browserul dumneavoastră și nu sunt încărcate nicăieri și nici puse în URL. Un token activ oferă totuși acces, așa că preferați tokenuri expirate sau de test.
Poate decodorul să citească un JWT criptat?
Nu. Tokenurile criptate (JWE) au cinci părți și au nevoie de cheia de decriptare. Decodorul lucrează cu tokenuri semnate (JWS), care au trei părți.
De ce eșuează verificarea cu secretul corect?
Verificați dacă secretul este păstrat ca base64url (bifați opțiunea), dacă tokenul a fost modificat și dacă algoritmul din antet se potrivește cu tipul cheii.
Ce înseamnă alg none?
Tokenul nu are semnătură. Serverele nu trebuie să accepte niciodată tokenuri nesemnate pentru autentificare; decodorul le marchează drept critice.
De ce tokenul meu apare expirat, deși tocmai a fost emis?
Ceasul dispozitivului dumneavoastră sau al emitentului este greșit ori exp a fost scris în milisecunde în loc de secunde. Comparați cu iat.
Pot decoda un token fără cheie?
Da. Antetul și payload-ul sunt doar codificate base64url. Cheia este necesară pentru a verifica faptul că tokenul este autentic.
Ce este un JWKS?
Un JSON Web Key Set, adică un document JSON cu una sau mai multe chei publice, publicat de obicei de un furnizor de identitate. Copiați în decodor, ca JWK, cheia al cărei kid se potrivește cu antetul tokenului.
Ar trebui să folosesc HS256 sau RS256?
HS256 este potrivit când un singur serviciu emite și verifică tokenurile. RS256 ori ES256 sunt mai bune când mai multe servicii verifică tokenuri, pentru că au nevoie doar de cheia publică.
Poate fi revocat un JWT?
Nu de unul singur. Folosiți durate de viață scurte și păstrați pe server o listă de blocare cu valori jti sau o stare de sesiune, atunci când este nevoie de revocare imediată.