Vytvoriť podpísaný JSON Web Token (JWT)

Čo je JWT Builder?

JWT Builder je online nástroj, ktorý produkuje podpísaný JSON Web Token (JWT) z JSON payloadu a HMAC secretu. Adresovaný je vývojárom, ktorí potrebujú rýchlo generovať test token na overenie správania API, simulovať autentifikovanú session v Postman, alebo reprodukovať bug súvisiaci s expiráciou alebo scope tokena.

Na rozdiel od nášho JWT decoderu, ktorý sa uspokojí s čítaním existujúceho tokena, JWT Builder vyrába kompletný token: skladá header, kóduje payload, počíta HMAC podpis a skladá všetko vo formáte header.payload.signature očakávanom všetkými JWT knižnicami na trhu.

Prečo generovať JWT?

JWT builder nemá vokáciu vydávať produkčné tokeny. Je to predovšetkým nástroj vývoja a testov. Tu sú najbežnejšie scenáre:

• Integračné testy: produkovať predvídateľné JWT pre riadenie E2E testov, ktoré klepú na chránené endpointy bez závislosti na skutočnom identity provideri.
• API mocky: dočasne nahradiť volanie IdP lokálne podpísaným JWT s rovnakým testovacím secretom.
• Lokálny vývoj: pripojiť sa k vášmu backendu manuálnym generovaním tokena obsahujúceho požadované claims, bez nutnosti prechádzať celým OAuth2 flow.
• Dema: ilustrovať autentifikačný priebeh alebo workflow založený na permisiách bez skutočného IdP poruke.
• Reprodukcia bugov: vyfalešovať expirovaný token, token s nesprávnym aud, token bez určitých claims, na testovanie chybových ciest vášho API.
• Debugovanie custom parsera: injektovať špeciálne konštruované JWT pre testovanie vlastného parsera.

Zloženie JWT

Podpísaný JWT je zložený z troch segmentov oddelených bodkou, každý kódovaný v Base64URL (variant Base64 bez paddingu a s -/_ namiesto +//):

• Header: JSON objekt opisujúci podpisový algoritmus a typ tokena, napríklad {"alg":"HS256","typ":"JWT"}. JWT Builder ho automaticky generuje z algoritmu, ktorý zvolíte.
• Payload: ľubovoľný JSON objekt obsahujúci claims tokena (subjekt, permisie, expiračné dátumy). Je to časť, ktorú poskytujete.
• Signature: HMAC-SHA počítaný na konkatenácii base64url(header) + "." + base64url(payload) s vaším tajným kľúčom. Je to ona, čo garantuje integritu tokena.

Detailné prípady použitia

• API mock pre E2E testy: vaša Cypress alebo Playwright sada musí volať API, ktoré vyžaduje Authorization: Bearer .... Namiesto orchestrácie kompletného loginu pri každom teste podpisujeme JWT za behu so zdieľaným secretom a injektujeme ho do hlavičky.
• SSO demo: prezentovať federovaný autentifikačný priebeh bez závislosti na online IdP.
• Test fixture: generovať deterministický JWT zo známeho payloadu pre slúženie ako stabilná fixture v unit testoch.
• Diagnostika custom parsera: testovať vlastný JWT parser s tokenmi zámerne minimálnymi alebo zámerne podivnými (chýbajúce claims, neočakávané typy).
• Učenie: konkrétne pochopiť, ako sa JWT konštruuje, modifikáciou payloadu a sledovaním zmeny podpisu.

Podporované algoritmy: HS256, HS384, HS512

Náš nástroj podporuje tri štandardné HMAC algoritmy JWT špecifikácie (RFC 7519):

• HS256: HMAC so SHA-256. Podpis 32 bajtov. Najpoužívanejší v praxi, dobrý kompromis medzi rýchlosťou a kryptografickou solídnosťou. Defaultne odporúčaný.
• HS384: HMAC so SHA-384. Podpis 48 bajtov. Vhodný pre kontexty vyžadujúce vyššiu bezpečnostnú maržu.
• HS512: HMAC so SHA-512. Podpis 64 bajtov. Najrobustnejší, za cenu mierne objemnejšieho tokena.

HMAC alebo RSA?

Algoritmy HS* sú symetrické: rovnaký kľúč slúži na podpisovanie aj overovanie. Je to jednoduché a rýchle, ale to znamená, že každý servis schopný overiť token je tiež schopný ho vydávať. Ak potrebujete oddeliť tieto dve role (jeden vydavateľ, viacero konzumentov), obráťte sa na RS256/RS384/RS512 algoritmy (RSA, asymetrické), ktoré môžete overiť naším JWT verifierom.

Bezpečnosť: chráňte váš secret

Bezpečnosť JWT podpísaného v HMAC spočíva kompletne na dôvernosti secretu. Niekoľko základných pravidiel:

• Použite dlhý a náhodný secret. RFC 7518 odporúča minimálne veľkosť výstupu algoritmu (32 bajtov pre HS256, 48 pre HS384, 64 pre HS512). Ľudské heslo ako azerty123 je triviálne napadnuteľné offline hrubou silou.
• Nikdy nepodpisujte JWT na strane klienta. Secret by skončil v JavaScript kóde distribuovanom do prehliadača, exponovanom každému užívateľovi. Podpis musí vždy zostať na strane servera.
• Uložte secret v environment premennej (napr. JWT_SECRET), nikdy v Git repozitári. Myslite na použitie trezora ako HashiCorp Vault, AWS Secrets Manager alebo Symfony Secrets podľa vášho stacku.
• Pravidelne rotujte secret (key rotation), najmä po každom incidente alebo odchode osoby, ktorá mala prístup ku konfigurácii.
• JWT Builder je určený na testy a učenie. Pre produkciu použite JWT knižnicu vášho frameworku (lcobucci/jwt, firebase/php-jwt, jose-php).

Dobré praktiky claims

Payload je voľný JSON objekt, ale RFC 7519 definuje sadu registered claims, ktoré JWT knižnice vedia interpretovať. Zahrnutie správnych claims robí váš token portabilným a vyhýba sa jemným bugom:

• iss (issuer): identifikátor vydavateľa, napríklad "https://api.example.com".
• sub (subject): identifikátor osoby alebo entity dotknutej, často ID užívateľa.
• aud (audience): pre koho je token určený, na zabránenie znovupoužitia tokena na inom API.
• exp (expiration time): Unix timestamp, po ktorom token už nie je validný. Vždy zahrnúť, aj pre test token: token bez expirácie je zlý zvyk, ťažko opraviteľný neskôr.
• nbf (not before): timestamp, pred ktorým ešte token nie je validný. Užitočné pre predvydanie tokena aktivovateľného neskôr.
• iat (issued at): timestamp vydania, užitočný pre logovanie a revokáciu.
• jti (JWT ID): unikátny identifikátor tokena, nepostrádateľný pre idempotenciu a implementáciu revokačného zoznamu.

Prí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"
}

Ako používať nástroj

1. Zadajte payload vo forme validného JSON. Je to objekt, takže začína { a končí }.
2. Indikujte HMAC secret. Vyberte dlhý a náhodný reťazec pre produkčné tokeny.
3. Vyberte algoritmus: HS256 defaultne, HS384 alebo HS512 podľa vašich potrieb.
4. Kliknite na vytvoriť. Podpísaný JWT sa objaví, pripravený na vloženie do Authorization: Bearer ... hlavičky.
5. Token môžete potom overiť s rovnakým secretom pre potvrdenie koherencie round-tripu, alebo ho dekódovať pre prečítanie jeho obsahu.

Často kladené otázky

Ukážka požiadavky

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šetky dostupné nástroje
• GET https://cdrn.fr/api/v1/tools/jwt-builder - získa schému tohto nástroja
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - spustí tento nástroj s JSON payloadom