Ověřit podpis JSON Web Token (JWT)

Proč verifikovat podpis JWT?

JSON Web Token (JWT) se rozkládá na tři části oddělené tečkami: header.payload.signature. Dekódování JWT spočívá jednoduše ve čtení prvních dvou částí (které jsou v Base64URL). Kdokoli to může udělat, a kdokoli může vyrobit JWT s libovolným payloadem. To, co dělá JWT důvěryhodným, je výhradně podpis: bez verifikace přijmout JWT znamená pustit k sobě domů jakoukoli osobu, která tvrdí, že je někým, bez požadavku na občanský průkaz.

Tento nástroj verifikuje podpis JWT pomocí klíče. Nespokojuje se s dekódováním: přepočítává podpis z headeru, payloadu a vašeho klíče, pak ho porovnává s podpisem tokenu. Pokud se oba shodují, token je autentický. Jinak byl vyroben, modifikován, nebo podepsán jiným klíčem.

Verifikace je úhelným kamenem každé architektury, která používá JWT pro autentifikaci nebo autorizaci: bez validního podpisu může payload lhát. Útočník, který by modifikoval "role":"user" na "role":"admin", by neměl žádné potíže to udělat, pokud by server verifikoval pouze formát tokenu a ne jeho podpis.

Běžné algoritmy

JWT specifikace (RFC 7518, JSON Web Algorithms) definuje několik rodin algoritmů. Zde jsou nejpoužívanější v produkci:

• HMAC (HS256, HS384, HS512): symetrický podpis založený na HMAC-SHA. Stejný secret slouží k podpisu a verifikaci. Jednoduché k zavedení, výkonné, ale jakákoli strana schopná verifikovat token je také schopná ho vydat. Vhodné pro scénáře, kde vydavatel a verifikátor jsou stejný tým nebo stejná služba.
• RSA (RS256, RS384, RS512): asymetrický podpis. Privátní klíč podepisuje, veřejný klíč verifikuje. Ideální když vydavatel a verifikátoři jsou různé entity (OAuth2, OpenID Connect, identity federation). Je to preferovaný algoritmus většiny veřejných identity providerů.
• ECDSA (ES256, ES384): asymetrický podpis na eliptických křivkách. Stejná logika jako RSA (privátní klíč pro podpis, veřejný pro verifikaci), ale s kompaktnějšími klíči a podpisy pro ekvivalentní úroveň zabezpečení. Stále více rozšířený v moderních architekturách.

Jak dodat klíč

Formát očekávaného klíče závisí na algoritmu deklarovaném v headeru JWT:

• HS256, HS384, HS512: klíč je secret string. Je to secret sdílený s vydavatelem, často uložený v environment variable jako JWT_SECRET. Žádné zvláštní formátování, jen surová hodnota.
• RS256, RS384, RS512: klíč je RSA veřejný klíč ve formátu PEM, který začíná -----BEGIN PUBLIC KEY----- a končí -----END PUBLIC KEY-----. Zachovejte zalomení řádků jak jsou, jinak OpenSSL odmítne ho parsovat.
• ES256, ES384: klíč je ECDSA veřejný klíč ve formátu PEM, na odpovídající křivce (P-256 pro ES256, P-384 pro ES384).

Příklad očekávaného RSA veřejného klíče

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

Jak funguje verifikace?

Náš server přesně reprodukuje operaci, kterou udělal vydavatel:

1. Rozdělí JWT na header, payload a podpis.
2. Konkatenuje base64url(header) + "." + base64url(payload).
3. Pro HMAC počítá HMAC-SHA-256/384/512 s vaším secretem, pak porovnává s přijatým podpisem přes hash_equals (constant-time porovnání pro zabránění timing útokům).
4. Pro RSA volá openssl_verify s vaším veřejným klíčem ve formátu PEM.

Případy použití

• Debug API autentifikace: dostáváte 401, ověřujete, zda je váš token opravdu podepsán očekávaným klíčem.
• Validace tokenu přijatého od providera: partner (Auth0, Keycloak, Cognito, Okta) vám posílá JWT podepsané v RS256; chcete potvrdit, že pochází od něj jeho veřejným klíčem.
• Bezpečnostní audit: ověřit, že třetí služba správně podepisuje své tokeny robustním algoritmem, a ne v HS256 se slabým secretem.
• Manuální testy: ověřit, že JWT generovaný vaším kódem správně prochází verifikací s dodaným veřejným klíčem.
• Rychlá verifikace přijatého tokenu: během integrace SSO nebo partnerského API ověřit za pár sekund, že podpisový/klíčový řetězec funguje před psaním jakéhokoli řádku kódu.

Jak nástroj používat

1. Vložte kompletní JWT (tři části oddělené tečkami).
2. Uveďte klíč přizpůsobený algoritmu headeru:
   • Pro HS256, HS384 nebo HS512 je klíč sdílený secret string s vydavatelem. Je to volný řetězec, často uložený v environment variable jako JWT_SECRET.
   • Pro RS256, RS384 nebo RS512 je klíč veřejný klíč ve formátu PEM, který začíná -----BEGIN PUBLIC KEY----- a končí -----END PUBLIC KEY-----.
3. Spusťte verifikaci. Nástroj zobrazí status (validní nebo nevalidní) a dekódovaný payload.

Běžné pasti k vyhnutí

• Algoritmus "none": spec povoluje alg: none, což znamená "bez podpisu". Klasická díra spočívá ve vyrobení tokenu s tímto headerem v naději, že server ho přijme. Náš nástroj systematicky odmítá tokeny s alg: none.
• HMAC vs RSA záměna (algorithm confusion): útočník změní algoritmus RS256 na HS256 a podepíše payload veřejným RSA klíčem použitým jako HMAC secret. Pokud server algoritmus nekontroluje, přijme token. Vždy zablokujte očekávaný algoritmus na straně serveru.
• HMAC secrets natvrdo v kódu: secret commitnutý v Git repozitáři činí celou důvěru tokenů kaducní. Ukládejte secrety v environment variables nebo aplikačním trezoru.
• Veřejný klíč vs privátní klíč: pro verifikaci JWT podepsaného v RSA nebo ECDSA se poskytuje veřejný klíč, nikdy privátní. Privátní slouží pouze k podpisu a nesmí nikdy opustit vydavatele.
• Ignorovaná expirace: validní podpis na expirovaném tokenu nesmí být nikdy přijat. Pamatujte ověřit exp a nbf.
• Nezkontrolovaná audience: token určený API A by neměl být přijat API B. Ověřte claim aud.

Časové claims: exp a nbf

Kromě podpisu musí validní JWT také respektovat časové omezení:

• exp (expiration): token již není validní po tomto datu.
• nbf (not before): token ještě není validní před tímto datem.

Náš nástroj explicitně signalizuje, když je token expirovaný nebo ještě nevalidní, i když je jeho podpis správný. Je to důležité: validní podpis na expirovaném tokenu nesmí být nikdy přijat v produkci.

Rozdíl od našeho JWT decoderu

Náš JWT decoder se spokojuje s dekódováním header a payload částí pro jejich učinění čitelnými. Neprovádí žádnou verifikaci podpisu a nevyžaduje klíč. Použijte ho pro rychlou inspekci obsahu tokenu. Použijte JWT verifier (tato stránka), jakmile potřebujete dokázat, že je token autentický. Pro výrobu podepsaného JWT pro testovací účely použijte náš JWT builder.

Často kladené otázky

Ukázka požadavku

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

Vstupní schéma

Koncové body

• GET https://cdrn.fr/api/v1/tools - vypíše všechny dostupné nástroje
• GET https://cdrn.fr/api/v1/tools/jwt-verifier - získá schéma tohoto nástroje
• POST https://cdrn.fr/api/v1/tools/jwt-verifier/execute - spustí tento nástroj s JSON payloadem