Een ondertekend JSON Web Token (JWT) aanmaken

Wat is JWT Builder?

JWT Builder is een online tool die een ondertekend JSON Web Token (JWT) produceert vanuit een JSON-payload en een HMAC-secret. Het richt zich op ontwikkelaars die snel een testtoken moeten genereren om het gedrag van een API te verifiëren, een geauthenticeerde sessie te simuleren in Postman, of een bug gerelateerd aan token-vervaldatum of -scope te reproduceren.

In tegenstelling tot onze JWT decoder, die zich beperkt tot het lezen van een bestaand token, fabriceert JWT Builder een volledig token: hij bouwt de header, codeert de payload, berekent de HMAC-handtekening en assembleert het geheel in het compacte formaat header.payload.signature dat door alle JWT-bibliotheken op de markt wordt verwacht.

Waarom een JWT genereren?

Een JWT-builder is niet bedoeld om productietokens uit te geven. Het is bovenal een tool voor ontwikkeling en tests. Dit zijn de meest voorkomende scenario's:

• Integratietests: voorspelbare JWT's produceren om E2E-tests aan te sturen die beveiligde endpoints raken zonder afhankelijk te zijn van de echte identiteitsprovider.
• API-mocks: een IdP-oproep tijdelijk vervangen door een JWT lokaal ondertekend met hetzelfde testgeheim.
• Lokale ontwikkeling: verbinden met uw eigen backend door handmatig een token te genereren met de gewenste claims, zonder de volledige OAuth2-flow te hoeven doorlopen.
• Demo's: een authenticatieparcours of een op rechten gebaseerde workflow illustreren zonder een echte IdP bij de hand te hebben.
• Bug-reproductie: een verlopen token, een token met een verkeerde aud, een token zonder bepaalde claims smeden, om de foutpaden van uw API te testen.
• Debug van een custom parser: speciaal geconstrueerde JWT's injecteren om een zelfgemaakte parser te testen.

Samenstelling van een JWT

Een ondertekende JWT bestaat uit drie segmenten gescheiden door een punt, elk gecodeerd in Base64URL (Base64-variant zonder padding en met -/_ in plaats van +//):

• Header: een JSON-object dat het handtekeningsalgoritme en het tokentype beschrijft, bijvoorbeeld {"alg":"HS256","typ":"JWT"}. JWT Builder genereert dit automatisch vanuit het algoritme dat u kiest.
• Payload: een willekeurig JSON-object dat de claims van het token bevat (subject, permissies, vervaldata). Dat is het deel dat u levert.
• Signature: een HMAC-SHA berekend op de concatenatie base64url(header) + "." + base64url(payload) met uw geheime sleutel. Zij garandeert de integriteit van het token.

Gebruiksgevallen in detail

• Mock-API voor E2E-tests: uw Cypress- of Playwright-testsuite moet een API aanroepen die Authorization: Bearer ... vereist. In plaats van een volledige login bij elke test te orkestreren, ondertekent men een JWT on the fly met het gedeelde geheim en injecteert deze in de header.
• SSO-demo: een gefedereerd authenticatieparcours presenteren zonder afhankelijk te zijn van een online IdP.
• Testfixture: een deterministische JWT genereren vanuit een bekende payload om te dienen als stabiele fixture in unit-tests.
• Diagnose van een custom parser: een zelfgemaakte JWT-parser testen met opzettelijk minimale of opzettelijk vreemde tokens (ontbrekende claims, onverwachte typen).
• Leren: concreet begrijpen hoe een JWT wordt geconstrueerd, door de payload te wijzigen en de handtekening te zien veranderen.

Ondersteunde algoritmen: HS256, HS384, HS512

Onze tool ondersteunt de drie standaard HMAC-algoritmen van de JWT-specificatie (RFC 7519):

• HS256: HMAC met SHA-256. Handtekening van 32 bytes. Het meest gebruikt in de praktijk, goede afweging tussen snelheid en cryptografische soliditeit. Standaard aanbevolen.
• HS384: HMAC met SHA-384. Handtekening van 48 bytes. Geschikt voor contexten die een hogere beveiligingsmarge vereisen.
• HS512: HMAC met SHA-512. Handtekening van 64 bytes. Het meest robuust, ten koste van een licht omvangrijker token.

HMAC of RSA?

De HS*-algoritmen zijn symmetrisch: dezelfde sleutel dient om te ondertekenen en te verifiëren. Dat is eenvoudig en snel, maar het betekent dat elke service die een token kan verifiëren ook in staat is om er een uit te geven. Als u deze twee rollen moet scheiden (één uitgever, meerdere consumenten), wendt u zich tot de algoritmen RS256/RS384/RS512 (RSA, asymmetrisch), die u kunt verifiëren met onze JWT verifier.

Beveiliging: bescherm uw geheim

De beveiliging van een in HMAC ondertekend JWT berust volledig op de vertrouwelijkheid van het geheim. Enkele basisregels:

• Gebruik een lang en willekeurig geheim. RFC 7518 raadt minimaal de uitvoergrootte van het algoritme aan (32 bytes voor HS256, 48 voor HS384, 64 voor HS512). Een menselijk wachtwoord zoals azerty123 is triviaal aanvalbaar door brute force offline.
• Onderteken nooit een JWT aan de clientkant. Het geheim zou in de naar de browser gedistribueerde JavaScript-code terechtkomen, blootgesteld aan elke gebruiker. De handtekening moet altijd aan de serverkant blijven.
• Bewaar het geheim in een omgevingsvariabele (bv. JWT_SECRET), nooit in een Git-repository. Denk eraan een kluis te gebruiken zoals HashiCorp Vault, AWS Secrets Manager of Symfony Secrets afhankelijk van uw stack.
• Roteer het geheim regelmatig (key rotation), vooral na elk incident of vertrek van iemand die toegang had tot de configuratie.
• JWT Builder is bedoeld voor tests en leren. Voor productie, gebruik de JWT-bibliotheek van uw framework (lcobucci/jwt, firebase/php-jwt, jose-php).

Goede claim-praktijken

De payload is een vrij JSON-object, maar RFC 7519 definieert een reeks registered claims die JWT-bibliotheken weten te interpreteren. Het opnemen van de juiste claims maakt uw token draagbaar en vermijdt subtiele bugs:

• iss (issuer): identifier van de uitgever, bijvoorbeeld "https://api.example.com".
• sub (subject): identifier van de betrokken persoon of entiteit, vaak het gebruikers-ID.
• aud (audience): voor wie het token bestemd is, om het hergebruik van een token op een andere API te voorkomen.
• exp (expiration time): Unix-tijdstempel waarna het token niet meer geldig is. Altijd opnemen, zelfs voor een testtoken: een token zonder vervaldatum is een slechte gewoonte die later moeilijk te corrigeren is.
• nbf (not before): tijdstempel vóór welke het token nog niet geldig is. Nuttig om een token vooruit uit te geven dat later activeerbaar is.
• iat (issued at): tijdstempel van uitgifte, nuttig voor het loggen en herroepen.
• jti (JWT ID): unieke identifier van het token, onmisbaar voor idempotentie en voor het implementeren van een herroepingslijst.

Voorbeeld van een typische payload

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

Hoe u de tool gebruikt

1. Voer de payload in als geldige JSON. Het is een object, dus het begint met { en eindigt met }.
2. Geef het HMAC-geheim aan. Kies een lange en willekeurige tekenreeks voor productietokens.
3. Selecteer het algoritme: HS256 standaard, HS384 of HS512 afhankelijk van uw behoeften.
4. Klik op maken. De ondertekende JWT verschijnt, klaar om te plakken in een Authorization: Bearer ...-header.
5. U kunt vervolgens het token verifiëren met hetzelfde geheim om de consistentie van de round-trip te bevestigen, of decoderen om de inhoud te herlezen.

Veelgestelde vragen

Voorbeeldverzoek

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

Invoerschema

Endpoints

• GET https://cdrn.fr/api/v1/tools - toont alle beschikbare tools
• GET https://cdrn.fr/api/v1/tools/jwt-builder - geeft het schema van deze tool terug
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - voert deze tool uit met een JSON-payload