Crearea unui JSON Web Token (JWT) semnat

Ce este JWT Builder?

JWT Builder este un instrument online care produce un JSON Web Token semnat (JWT) dintr-un payload JSON și un secret HMAC. Se adresează dezvoltatorilor care au nevoie să genereze rapid un token de test pentru a verifica comportamentul unui API, a simula o sesiune autentificată în Postman, sau a reproduce un bug legat de expirarea sau aria de aplicare a unui token.

Contrar JWT decoder-ului nostru, care se mulțumește să citească un token existent, JWT Builder fabrică un token complet: construiește header-ul, codează payload-ul, calculează semnătura HMAC și asamblează totul în format compact header.payload.signature așteptat de toate bibliotecile JWT de pe piață.

De ce să generezi un JWT?

Un builder de JWT nu are vocația de a emite token-uri de producție. Este înainte de toate un instrument de dezvoltare și teste. Iată scenariile cele mai curente:

• Teste de integrare: a produce JWT-uri previzibile pentru a pilota teste E2E care lovesc endpoint-uri protejate fără a depinde de adevăratul furnizor de identitate.
• Mock-uri de API: a înlocui temporar un apel la IdP cu un JWT semnat local cu același secret de test.
• Dezvoltare locală: a te conecta la propriul backend generând manual un token conținând claim-urile dorite, fără a fi nevoie să treci prin tot flow-ul OAuth2.
• Demo-uri: a ilustra un parcurs de autentificare sau un workflow bazat pe permisiuni fără a avea un IdP real la îndemână.
• Reproducere de bug-uri: a forja un token expirat, un token cu un aud incorect, un token fără anumite claim-uri, pentru a testa căile de eroare ale API-ului tău.
• Debugging al unui parser custom: a injecta JWT-uri special construite pentru a testa un parser maison.

Compoziția unui JWT

Un JWT semnat este compus din trei segmente separate de un punct, fiecare codat în Base64URL (variantă a Base64 fără padding și cu -/_ în loc de +//):

• Header: un obiect JSON care descrie algoritmul de semnătură și tipul token-ului, de exemplu {"alg":"HS256","typ":"JWT"}. JWT Builder îl generează automat plecând de la algoritmul pe care îl alegi.
• Payload: un obiect JSON arbitrar care conține claim-urile token-ului (subiect, permisiuni, date de expirare). Este partea pe care o furnizezi.
• Semnătură: un HMAC-SHA calculat pe concatenarea base64url(header) + "." + base64url(payload) cu cheia ta secretă. Ea este cea care garantează integritatea token-ului.

Cazuri de utilizare în detaliu

• API mock pentru teste E2E: suita ta Cypress sau Playwright trebuie să apeleze un API care cere un Authorization: Bearer .... În loc să orchestrezi un login complet la fiecare test, se semnează un JWT din mers cu secretul partajat și se injectează în header.
• Demo SSO: a prezenta un parcurs de autentificare federată fără a depinde de un IdP online.
• Fixture de test: a genera un JWT determinist dintr-un payload cunoscut pentru a servi drept fixture stabil în teste unitare.
• Diagnostic al unui parser custom: a testa un parser JWT maison cu token-uri voit minimale sau voit ciudate (claim-uri lipsă, tipuri neașteptate).
• Învățare: a înțelege concret cum se construiește un JWT, modificând payload-ul și observând semnătura schimbându-se.

Algoritmi suportați: HS256, HS384, HS512

Instrumentul nostru suportă cei trei algoritmi HMAC standard ai specificației JWT (RFC 7519):

• HS256: HMAC cu SHA-256. Semnătură de 32 de octeți. Cel mai utilizat în practică, bun compromis între rapiditate și soliditate criptografică. Recomandat implicit.
• HS384: HMAC cu SHA-384. Semnătură de 48 de octeți. Adaptat contextelor care cer o marjă de securitate superioară.
• HS512: HMAC cu SHA-512. Semnătură de 64 de octeți. Cel mai robust, cu prețul unui token ușor mai voluminos.

HMAC sau RSA?

Algoritmii HS* sunt simetrici: aceeași cheie servește la semnare și la verificare. Este simplu și rapid, dar înseamnă că orice serviciu capabil să verifice un token este de asemenea capabil să emită unul. Dacă ai nevoie să separi aceste două roluri (un singur emitent, mai mulți consumatori), îndreaptă-te spre algoritmii RS256/RS384/RS512 (RSA, asimetrici), pe care îi poți verifica cu JWT verifier-ul nostru.

Securitate: protejarea secretului tău

Securitatea unui JWT semnat în HMAC se bazează integral pe confidențialitatea secretului. Câteva reguli de bază:

• Utilizează un secret lung și aleatoriu. RFC 7518 recomandă cel puțin dimensiunea ieșirii algoritmului (32 de octeți pentru HS256, 48 pentru HS384, 64 pentru HS512). O parolă umană precum azerty123 este trivial atacabilă prin forță brută offline.
• Nu semna niciodată un JWT pe partea clientului. Secretul s-ar regăsi în codul JavaScript distribuit browserului, expus oricărui utilizator. Semnătura trebuie întotdeauna să rămână pe partea serverului.
• Stochează secretul într-o variabilă de mediu (ex. JWT_SECRET), niciodată într-un depozit Git. Gândește-te să utilizezi un seif precum HashiCorp Vault, AWS Secrets Manager sau Symfony Secrets în funcție de stack-ul tău.
• Rotește secretul regulat (key rotation), mai ales după orice incident sau plecare a unei persoane care a avut acces la configurație.
• JWT Builder este destinat testelor și învățării. Pentru producție, utilizează biblioteca JWT a framework-ului tău (lcobucci/jwt, firebase/php-jwt, jose-php).

Bune practici de claim-uri

Payload-ul este un obiect JSON liber, dar RFC 7519 definește un set de registered claims pe care bibliotecile JWT le știu interpreta. Includerea claim-urilor potrivite face token-ul tău portabil și evită bug-uri subtile:

• iss (issuer): identificator al emitentului, de exemplu "https://api.example.com".
• sub (subject): identificator al persoanei sau entității vizate, adesea ID-ul utilizator.
• aud (audience): cui îi este destinat token-ul, pentru a împiedica reutilizarea unui token pe alt API.
• exp (expiration time): timestamp Unix după care token-ul nu mai este valid. Întotdeauna includ, chiar și pentru un token de test: un token fără expirare este o obișnuință proastă greu de corectat ulterior.
• nbf (not before): timestamp înainte de care token-ul nu este încă valid. Util pentru a preemite un token activabil mai târziu.
• iat (issued at): timestamp de emitere, util pentru a jurnaliza și a revoca.
• jti (JWT ID): identificator unic al token-ului, indispensabil pentru idempotență și pentru a implementa o listă de revocare.

Exemplu de payload tipic

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

Cum să utilizezi instrumentul

1. Introdu payload-ul sub forma unui JSON valid. Este un obiect, deci începe cu { și se termină cu }.
2. Indică secretul HMAC. Alege un șir lung și aleatoriu pentru token-urile de producție.
3. Selectează algoritmul: HS256 implicit, HS384 sau HS512 în funcție de nevoile tale.
4. Apasă pe creează. JWT-ul semnat apare, gata de lipit într-un header Authorization: Bearer ....
5. Poți apoi verifica token-ul cu același secret pentru a confirma coerența round-trip-ului, sau să-l decodezi pentru a relucra conținutul său.

Întrebări frecvente

Exemplu de cerere

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

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-builder - obține schema acestui instrument
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - execută acest instrument cu un payload JSON