Wat zit er in een JWT? Decoderen is niet verifiëren

Een JSON Web Token (JWT) bestaat uit drie stukken tekst die met punten aan elkaar zijn gekoppeld: een header, een payload en een handtekening. De eerste twee zijn alleen gecodeerd, niet versleuteld, dus iedereen die het token heeft, kan ze lezen. De handtekening laat een server controleren of een vertrouwde partij het token heeft uitgegeven en of niemand het heeft aangepast. Een token decoderen laat zien wat erin staat. Alleen verifiëren laat zien of je het kunt vertrouwen.

JWT-decoderToken verlopen, of is hij geldig?Gratis doen

De drie delen

Een token ziet eruit als header.payload.signature. Het eerste deel van het bekende voorbeeldtoken van jwt.io is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Elk van de eerste twee delen is JSON die is omgezet naar base64url, een tekstvorm die veilig is in URL's. Het eerste deel decodeert naar:

{"alg":"HS256","typ":"JWT"}

De payload van hetzelfde voorbeeld decodeert naar:

{"sub":"1234567890","name":"John Doe","iat":1516239022}

De payload bevat de claims, uitspraken over de gebruiker of de sessie. De handtekening wordt berekend uit de eerste twee delen en een sleutel, dus als je één teken wijzigt, klopt de handtekening niet meer. Base64url is zonder sleutel om te keren. Zet daarom nooit een wachtwoord, een privésleutel of persoonsgegevens in een payload.

Geregistreerde claims

RFC 7519, de standaard voor JWT's, reserveert een paar korte claimnamen:

iss (issuer): wie het token heeft aangemaakt.
sub (subject): over wie het token gaat, meestal een gebruikers-ID.
aud (audience): de dienst waarvoor het token bedoeld is.
exp (expiration time): het moment waarna het token ongeldig is.
nbf (not before): het vroegste moment waarop het token geldig is.
iat (issued at): wanneer het token is aangemaakt.

Tijden zijn seconden sinds 1 januari 1970 UTC, Unixtijd genoemd. Het voorbeeld heeft geen exp, dus volgens de standaard verloopt het nooit. Een echt token zou er een moeten hebben. Andere namen, zoals role of email, horen bij de toepassing.

Decoderen is niet verifiëren

Bij decoderen wordt het token bij de punten gesplitst, de base64url omgekeerd en de JSON gelezen. Je ziet wat het token beweert. Dat geldt ook voor een vervalst token, want iedereen kan elke claim met elke handtekening schrijven.

Bij verifiëren wordt de handtekening opnieuw berekend met de juiste sleutel en gecontroleerd of die overeenkomt. Ook wordt gecontroleerd of exp en nbf de huidige tijd omvatten, en of iss en aud de waarden zijn die de dienst verwacht. Een app die een role-claim leest zonder te verifiëren, vertrouwt degene die het token heeft geschreven. Dat is een veelgemaakte fout.

HS256, RS256 en ES256

De waarde van alg noemt de methode. Er zijn drie veelvoorkomende:

HS256 is HMAC met SHA-256. Eén gedeeld geheim ondertekent en verifieert, dus het geheim moet op de server blijven die de tokens uitgeeft.
RS256 is een RSA-handtekening met SHA-256. De uitgever ondertekent met een privésleutel, en iedereen met de publieke sleutel kan verifiëren. Andere diensten kunnen tokens controleren zonder ze zelf te kunnen maken.
ES256 is een ECDSA-handtekening met de P-256-curve en SHA-256. Het werkt als RS256, met kleinere sleutels en handtekeningen.

Gebruik HS256 als één dienst zowel de tokens uitgeeft als controleert. Gebruik RS256 of ES256 als andere diensten tokens moeten controleren die ze zelf niet hebben uitgegeven.

Problemen die ontstaan door de header te vertrouwen

De header wordt geschreven door wie het token verstuurt, dus de verifiërende partij mag die niet bepalen welke regels gelden.

alg: none. Een token zonder handtekening kan "alg":"none" opgeven. Sommige bibliotheken accepteerden zulke tokens vroeger en sloegen de controle over. Stel de toegestane algoritmen in je eigen code in en neem ze nooit uit het token over.
Algoritmeverwarring. Een server verwacht RS256 en heeft een publieke sleutel. Een aanvaller stuurt een HS256-token dat is ondertekend met die publieke sleutel als HMAC-geheim. Een verifier die elk algoritme accepteert dat de header noemt, accepteert het. Koppel elke sleutel aan precies één algoritme.
Zwakke geheimen. De aanvaller heeft de header, payload en handtekening, dus hij kan kandidaat-geheimen offline testen. Een kort geheim of een veelgebruikt woord valt zo snel. RFC 7518 stelt dat een HS256-sleutel minstens 256 bits moet zijn en willekeurig.

Een productietoken in een website plakken

Een geldig, niet-verlopen token werkt voor iedereen die het heeft, totdat het verloopt. Behandel het als een wachtwoord. Voordat je er een in een site plakt, kijk je of die site het naar een server stuurt. Een tool die volledig in het browsertabblad draait, heeft dat niet nodig. Je kunt elke pagina controleren door de netwerkverzoeken te bekijken in de ontwikkelaarstools van je browser.

Tokens kunnen meestal niet worden ingetrokken voordat ze verlopen, tenzij de server een lijst bijhoudt. Als een actief token lekt, vraag de dienst dan de sessie in te trekken of de sleutels te vervangen. Gebruik voor het debuggen waar mogelijk een token uit de testomgeving. De JWT-decoder leest de drie delen in je browsertabblad, en wat je plakt, wordt nergens naartoe gestuurd.

Webhooks: hetzelfde idee met een gedeeld geheim

De meeste webhookaanbieders sturen in een header een HMAC van de request-body, berekend met een geheim dat je met hen deelt. Je ontvanger berekent dezelfde HMAC en vergelijkt de twee. Veelvoorkomende fouten zijn klein. De JSON wordt opnieuw opgemaakt voordat hij wordt gehasht, waardoor de bytes veranderen. Het testgeheim wordt gebruikt bij live verkeer. Of de handtekeningen worden vergeleken met een gewone stringvergelijking, waardoor tijdinformatie kan lekken. Gebruik een vergelijking in constante tijd.

De webhook-handtekeningtester berekent de handtekening uit het geheim en de body die je plakt, voor GitHub, Stripe, Slack, Shopify of elk ander HMAC-schema, zodat je ziet of de twee waarden overeenkomen.

Korte antwoorden

Is een JWT versleuteld?

Nee. Een standaard-JWT is ondertekend, en iedereen kan de header en payload lezen. Alleen de handtekening beschermt tegen wijzigingen.

Wat gebeurt er als ik de payload aanpas?

De handtekening klopt niet meer, dus een verifiërende server wijst het token af. Het lezen van de claims controleert de handtekening niet, dus de decoder toont nog steeds je aangepaste versie.