Hoe weet een server, nadat u zich heeft aangemeld, dat elk later verzoek echt van u afkomstig is? Een populair antwoord is een JSON Web Token, of JWT, meestal uitgesproken als ‘jot’. Het is een klein, ondertekend stukje gegevens dat de client bij elk verzoek verzendt, en de server kan dit controleren zonder een database aan te raken.

De snelste manier om een ​​JWT te begrijpen, is door er een te bouwen en deze vervolgens te breken. We hebben dat gedaan met alleen de standaardbibliotheek van Python, op Python 3.13, en de onderstaande uitvoer komt uit die run. Deze code is bedoeld om te leren. Gebruik in een echte toepassing een goed onderhouden bibliotheek, omdat de details van de verificatie gemakkelijk fout kunnen gaan.

Wat is een JWT?

JWT is een open standaard, gedefinieerd in RFC 7519, voor het doorgeven van claims tussen twee partijen als een compacte string. Een claim is eenvoudigweg een verklaring, zoals “de ID van deze gebruiker is 42”. Omdat het token is ondertekend, kan de ontvanger bevestigen wie het heeft uitgegeven en dat niemand het heeft gewijzigd.

Denk hierbij aan een festivalbandje. Het personeel bij de poort controleert je ticket één keer en geeft je een band die moeilijk te vervalsen is. Daarna kijkt elke kraam alleen maar naar de band, zonder dat je de kassa hoeft te bellen. Een JWT werkt op vrijwel dezelfde manier voor een API.

Hoe JWT-aanmelding werkt

1. De gebruiker verzendt een gebruikersnaam en wachtwoord naar het inlogeindpunt.
2. De server controleert ze en maakt een ondertekend token.
3. De client slaat het token op.
4. Elk later verzoek bevat het, meestal in een header: Authorization: Bearer <token>.
5. De server verifieert de handtekening en de vervaldatum en leest vervolgens de claims.

Het belangrijkste voordeel zit in stap 5. De server hoeft geen sessie op te zoeken, wat handig is als veel services of servers hetzelfde token moeten controleren. Als u nog niet bekend bent met API’s, begin dan met wat is een API.

De drie delen van een JWT

Een JWT ziet eruit als willekeurige tekst, maar bestaat uit drie Base64URL-gecodeerde secties, gescheiden door punten. Hier is er een die we hebben gegenereerd:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNzkzNTAwMDAwLCJleHAiOjE3OTM1MDA5MDB9
.7YfUDH_T-iDh8bMmUT8mmKYwOstzT8Ty--DTTAmQGWM

We hebben regeleinden toegevoegd om het lezen gemakkelijker te maken. Het decoderen van de eerste twee delen levert duidelijke JSON op:

Header:  {"alg":"HS256","typ":"JWT"}
Payload: {"sub":"42","role":"user","iat":1793500000,"exp":1793500900}

Standaard claims

Je kunt ook aangepaste claims toevoegen, zoals role. Tijden zijn Unix-tijdstempels, in seconden. Houd de payload klein, aangezien het token met elk verzoek meegaat.

Bouw er zelf een

Het maken van een token omvat het coderen van de twee JSON-onderdelen en het vervolgens ondertekenen ervan met een geheim met behulp van HMAC-SHA256:

import base64, hashlib, hmac, json

SECRET = b"demo-secret-do-not-use-in-production"

def b64url(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()

def sign(message):
    return b64url(hmac.new(SECRET, message.encode(), hashlib.sha256).digest())

def create_token(payload):
    header = {"alg": "HS256", "typ": "JWT"}
    parts = [
        b64url(json.dumps(header, separators=(",", ":")).encode()),
        b64url(json.dumps(payload, separators=(",", ":")).encode()),
    ]
    message = ".".join(parts)
    return message + "." + sign(message)

Verificatie werkt door de handtekening opnieuw te berekenen en deze te vergelijken met die in het token. Alleen iemand met het geheim kan een bijpassend geheim produceren:

def verify_token(token, now):
    header, payload, signature = token.split(".")
    expected = sign(header + "." + payload)
    if not hmac.compare_digest(signature, expected):
        raise ValueError("bad signature")
    claims = json.loads(b64url_decode(payload))
    if claims["exp"] < now:
        raise ValueError("token expired")
    return claims

Een geldig token heeft de claims geretourneerd zoals verwacht. compare_digest wordt gebruikt omdat het in constante tijd draait, waardoor het lekken van informatie door timingverschillen wordt vermeden.

Probeer ermee te knoeien

Stel dat een aanvaller de payload decodeert, "role":"user" in "role":"admin" verandert, deze opnieuw codeert en de oude handtekening behoudt. We hebben dit geprobeerd, samen met twee andere aanvallen:

Die laatste poging richt zich op een echte historische zwakte. Sommige bibliotheken vertrouwden ooit op de eigen header van het token, zodat een aanvaller eenvoudigweg kon verklaren dat er geen handtekening nodig was. Onze code gebruikt altijd één vast algoritme en is daarom afgewezen. Geef in een echte bibliotheek altijd de algoritmen op die u accepteert.

Ondertekend, niet gecodeerd

Dit is het meest onbegrepen punt over JWT’s. Ons vervalste token werd afgewezen, maar de inhoud was nog steeds perfect leesbaar:

{"sub":"42","role":"admin","iat":1793500000,"exp":1793500900}

Base64URL is een codering, geen codering, en iedereen kan dit zonder enige sleutel omkeren. De handtekening verhindert dat mensen de gegevens wijzigen, maar niet lezen. Plaats dus nooit wachtwoorden, kaartnummers of persoonlijke privégegevens in een JWT-payload. Als de inhoud verborgen moet worden, gebruik dan gecodeerde tokens (JWE) of bewaar de gegevens gewoon op de server.

HS256 versus RS256

Met asymmetrische ondertekening kunnen andere diensten tokens verifiëren zonder hun eigen tokens te kunnen maken, wat de schade beperkt als er een wordt gecompromitteerd.

JWT versus sessies

JWT’s worden vaak gepresenteerd als een moderne vervanging voor sessies. In werkelijkheid heeft elk zijn afwegingen:

Voor een traditionele server-gerenderde website is een sessiecookie vaak eenvoudiger en veiliger. JWT’s zijn doorgaans zinvoller voor API’s die door verschillende services worden gebruikt, of voor mobiele clients.

Waar tokens in een browser kunnen worden opgeslagen

Veel beveiligingshandleidingen geven de voorkeur aan HttpOnly, Secure, SameSite cookies voor webapps. Welke je ook kiest, gebruik altijd HTTPS. Als u een token wilt verzenden vanuit JavaScript, raadpleegt u onze JavaScript Fetch API-tutorial.

Tokens vernieuwen

Een korte vervaldatum beperkt de schade van een gestolen token, maar niemand wil elke 15 minuten inloggen. De gebruikelijke oplossing gebruikt twee tokens:

• Toegangstoken: van korte duur, zoals minuten, en verzonden bij elk API-verzoek.
• Vernieuwingstoken: heeft een langere levensduur, wordt zorgvuldiger bewaard en wordt alleen gebruikt om nieuwe toegangstokens te verkrijgen.

De server houdt vernieuwingstokens bij, zodat hij deze kan intrekken, waardoor u praktisch kunt uitloggen. Door ze bij elk gebruik te roteren, kunt u ook diefstal opsporen, omdat een gestolen oud token opnieuw wordt afgespeeld.

Veel voorkomende beveiligingsfouten

• Decoderen zonder verificatie. Het lezen van een payload maakt deze niet betrouwbaar. Controleer altijd de handtekening.
• Elk algoritme accepteren. Stel een expliciete lijst met toegestane algoritmen in.
• Een zwak geheim gebruiken. Korte geheimen kunnen offline worden gekraakt. Gebruik een lange willekeurige waarde en houd deze buiten bronbeheer.
• Vervaldatum overslaan. Tokens zonder exp kunnen voor altijd blijven werken als ze worden gestolen.
• Niet controleren van iss en aud. Anders kan een token dat voor de ene dienst is uitgegeven, door een andere worden geaccepteerd.
• Vertrouwen op verouderde claims. Een rol binnen een token kan verouderd zijn totdat deze verloopt.
• Logboektokens. Iedereen die uw logboeken leest, kan deze opnieuw gebruiken.
• Foutpaden niet testen. Voeg tests toe voor verlopen en gewijzigde tokens, evenals voor geldige tokens. Onze gids voor API-testen met Postman kan hierbij helpen.

Tot slot

Een JWT bestaat uit ondertekende gegevens die een server kan vertrouwen zonder opzoeken, geen geheime container en geen automatische upgrade tijdens sessies. Gebruik een korte vervaldatum, verifieer alles met een onderhouden bibliotheek en houd privégegevens buiten de payload. Om het zelf te zien, voert u een klein script uit zoals het onze, wijzigt u één teken van een token en ziet u hoe de verificatie mislukt.

Veelgestelde vragen

Blijf leren