Vytvořit podepsaný JSON Web Token (JWT)

Co je JWT Builder?

JWT Builder je online nástroj, který produkuje podepsaný JSON Web Token (JWT) z JSON payload a HMAC secret. Cílí na developery, kteří potřebují rychle generovat testovací token pro ověření chování API, simulaci autentifikované session v Postmanu, nebo reprodukci bugu vázaného na expiraci nebo scope tokenu.

Na rozdíl od našeho JWT decoderu, který se spokojuje s čtením existujícího tokenu, JWT Builder vyrábí kompletní token: konstruuje header, kóduje payload, počítá HMAC podpis a sestavuje vše v kompaktním formátu header.payload.signature očekávaném všemi JWT knihovnami na trhu.

Proč generovat JWT?

Builder JWT nemá za cíl vydávat produkční tokeny. Je to především vývojový a testovací nástroj. Zde jsou nejběžnější scénáře:

• Integrační testy: produkovat předvídatelné JWT pro řízení E2E testů, které volají chráněné endpointy bez závislosti na skutečném identity provideru.
• API mocky: dočasně nahradit volání IdP lokálně podepsaným JWT stejným testovacím secretem.
• Lokální vývoj: připojit se k vlastnímu backendu manuální generací tokenu obsahujícího požadované claims, bez nutnosti procházet celý OAuth2 flow.
• Dema: ilustrovat průběh autentifikace nebo workflow založené na oprávněních bez skutečného IdP po ruce.
• Reprodukce bugů: vytvořit expirovaný token, token s nesprávným aud, token bez určitých claims, pro testování chybových cest vašeho API.
• Debug custom parseru: injektovat speciálně sestavené JWT pro testování domácího parseru.

Složení JWT

Podepsaný JWT je složen ze tří segmentů oddělených tečkou, každý kódovaný v Base64URL (variantě Base64 bez paddingu a s -/_ místo +//):

• Header: JSON objekt popisující podpisový algoritmus a typ tokenu, například {"alg":"HS256","typ":"JWT"}. JWT Builder ho automaticky generuje z algoritmu, který vyberete.
• Payload: arbitrární JSON objekt obsahující claims tokenu (subject, permissions, expirační data). Je to část, kterou poskytujete.
• Signature: HMAC-SHA počítaný na konkatenaci base64url(header) + "." + base64url(payload) s vaším secretem. Ona je tím, co garantuje integritu tokenu.

Případy použití do detailu

• API mock pro E2E testy: vaše Cypress nebo Playwright sada musí volat API, které vyžaduje Authorization: Bearer .... Místo orchestrace kompletního loginu při každém testu, podepíšeme JWT za běhu sdíleným secretem a injektujeme ho do headeru.
• Demo SSO: prezentovat federated autentifikační průběh bez závislosti na online IdP.
• Testovací fixture: generovat deterministický JWT ze známého payload pro stabilní fixture v unit testech.
• Diagnostika custom parseru: testovat domácí JWT parser s záměrně minimalními nebo záměrně podivnými tokeny (chybějící claims, neočekávané typy).
• Učení: konkrétně pochopit, jak se JWT konstruuje, modifikací payload a pozorováním změny podpisu.

Podporované algoritmy: HS256, HS384, HS512

Náš nástroj podporuje tři standardní HMAC algoritmy JWT specifikace (RFC 7519):

• HS256: HMAC s SHA-256. Podpis 32 bajtů. Nejpoužívanější v praxi, dobrý kompromis mezi rychlostí a kryptografickou solidností. Doporučeno výchozí.
• HS384: HMAC s SHA-384. Podpis 48 bajtů. Vhodný pro kontexty, které vyžadují vyšší bezpečnostní marži.
• HS512: HMAC s SHA-512. Podpis 64 bajtů. Nejrobustnější, za cenu mírně objemnějšího tokenu.

HMAC nebo RSA?

HS* algoritmy jsou symetrické: stejný klíč slouží k podpisu a verifikaci. Je to jednoduché a rychlé, ale to znamená, že každá služba schopná verifikovat token je také schopná ho vydávat. Pokud potřebujete oddělit tyto dvě role (jediný vydavatel, více konzumentů), obraťte se na RS256/RS384/RS512 algoritmy (RSA, asymetrické), které můžete verifikovat naším JWT verifierem.

Bezpečnost: chránit svůj secret

Bezpečnost JWT podepsaného HMAC spočívá výhradně na důvěrnosti secretu. Pár základních pravidel:

• Použijte dlouhý a náhodný secret. RFC 7518 doporučuje minimálně velikost výstupu algoritmu (32 bajtů pro HS256, 48 pro HS384, 64 pro HS512). Lidské heslo jako azerty123 je triviálně napadnutelné brute-force offline.
• Nikdy nepodepisujte JWT na straně klienta. Secret by se objevil v JavaScript kódu distribuovaném prohlížeči, vystaveném každému uživateli. Podpis musí vždy zůstat na straně serveru.
• Uložte secret do environment variable (např. JWT_SECRET), nikdy do Git repozitáře. Pomyslete na použití vaultu jako HashiCorp Vault, AWS Secrets Manager nebo Symfony Secrets podle vašeho stacku.
• Pravidelně rotujte secret (key rotation), zejména po jakémkoli incidentu nebo odchodu osoby, která měla přístup ke konfiguraci.
• JWT Builder je určen pro testy a učení. Pro produkci použijte JWT knihovnu vašeho frameworku (lcobucci/jwt, firebase/php-jwt, jose-php).

Osvědčené postupy claims

Payload je volný JSON objekt, ale RFC 7519 definuje sadu registered claims, které JWT knihovny umí interpretovat. Zahrnutí správných claims činí váš token přenosným a vyhne se subtilním bugům:

• iss (issuer): identifikátor vydavatele, například "https://api.example.com".
• sub (subject): identifikátor osoby nebo entity, často ID uživatele.
• aud (audience): komu je token určen, pro zabránění opětovnému použití tokenu na jiném API.
• exp (expiration time): Unix timestamp, po kterém token již není validní. Vždy zahrňte, i pro testovací token: token bez expirace je špatný zvyk obtížně později opravitelný.
• nbf (not before): timestamp před kterým token ještě není validní. Užitečné pro pre-vydávání tokenu aktivovatelného později.
• iat (issued at): timestamp vydání, užitečný pro logování a revokaci.
• jti (JWT ID): unikátní identifikátor tokenu, nezbytný pro idempotenci a implementaci revokačního seznamu.

Příklad typického payloadu

{
  "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"
}

Jak nástroj používat

1. Zadejte payload ve formě validního JSON. Je to objekt, takže začíná { a končí }.
2. Uveďte HMAC secret. Pro produkční tokeny vyberte dlouhý a náhodný řetězec.
3. Vyberte algoritmus: výchozí HS256, HS384 nebo HS512 podle vašich potřeb.
4. Klikněte na vytvořit. Podepsaný JWT se objeví, připravený k vložení do hlavičky Authorization: Bearer ....
5. Pak můžete verifikovat token stejným secretem pro potvrzení konzistence round-tripu, nebo ho dekódovat pro znovuvyčtení jeho obsahu.

Často kladené otázky

Ukázka požadavku

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

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-builder - získá schéma tohoto nástroje
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - spustí tento nástroj s JSON payloadem