JWT sicher verwenden

Typische Sicherheitsfehler mit JSON Web Tokens und wie Sie sie vermeiden: alg none, schwache Schlüssel, fehlende Prüfungen und Speicherort.

JSON Web Tokens (JWT) sind in APIs, Single-Page-Apps und beim Single Sign-on weit verbreitet. Das Format selbst ist solide – Sicherheitslücken entstehen fast immer dadurch, wie ein Token erzeugt, geprüft und aufbewahrt wird. Viele dieser Fehler wiederholen sich so regelmäßig, dass die IETF ihnen ein eigenes Dokument gewidmet hat: RFC 8725, die „JSON Web Token Best Current Practices“.

Diese Anleitung erklärt kurz den Aufbau eines JWT und geht dann die typischen Schwachstellen durch – mit einer Checkliste am Ende.

Aufbau: Header, Payload, Signatur

Ein JWT nach RFC 7519 besteht aus drei Teilen, die durch Punkte getrennt sind:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6IjQ3MTEiLCJyb2xlIjoiZWRpdG9yIiwiaWF0IjoxNzk1MTY5NzAwLCJleHAiOjE3OTUxNzA2MDB9
.OtRAsLUrCdDBZw927bOeIHqfxapz4AZesbLJXlP9iMU

(Zur besseren Lesbarkeit umbrochen; ein echtes Token steht in einer Zeile.) Header und Payload sind JSON-Objekte, die mit Base64url kodiert wurden. Dekodiert sieht das so aus:

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

{
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "sub": "4711",
  "role": "editor",
  "iat": 1795169700,
  "exp": 1795170600
}

Der dritte Teil ist die Signatur über Header und Payload. Wichtig: Base64url ist keine Verschlüsselung. Jeder, der das Token hat, kann den Inhalt lesen – etwa mit dem JWT-Debugger, der Header und Payload dekodiert und die Zeitangaben als Datum anzeigt, oder manuell mit dem Base64-Decoder und dem JSON-Formatter. Die Signatur verhindert nur, dass jemand den Inhalt unbemerkt ändert.

Dieses Format heißt genauer JWS (JSON Web Signature). Daneben gibt es JWE (JSON Web Encryption): Dort ist der Inhalt verschlüsselt, das Token hat fünf statt drei Teile. JWE ist deutlich seltener und aufwendiger; in den meisten Anwendungen ist es einfacher, vertrauliche Daten gar nicht erst ins Token zu schreiben.

Signatur richtig prüfen

Algorithmus festlegen, nicht aus dem Token übernehmen

Der Header nennt im Feld alg den Algorithmus. Dieses Feld stammt aber vom Absender – und ist damit vom Angreifer kontrollierbar. Daraus ergeben sich zwei bekannte Angriffe:

  • alg: none: Die Spezifikation kennt unsignierte Tokens. Akzeptiert eine Bibliothek sie, genügt es, im Header {"alg":"none"} einzutragen, die Payload beliebig zu ändern und die Signatur wegzulassen.
  • Verwechslung von RS256 und HS256: Ein Server prüft RS256-Tokens mit einem öffentlichen Schlüssel. Ein Angreifer setzt alg auf HS256 und signiert mit genau diesem öffentlichen Schlüssel als HMAC-Geheimnis. Übernimmt die Bibliothek den Algorithmus aus dem Token, gilt die Signatur als gültig.

Die Lösung ist in beiden Fällen dieselbe: Legen Sie auf dem Server fest, welche Algorithmen erlaubt sind, und lehnen Sie alle anderen ab. Ein Beispiel mit der Node-Bibliothek jose:

const { payload } = await jwtVerify(token, publicKey, {
  algorithms: ['RS256'],
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
  clockTolerance: 30,
});

Auch der JWT-Debugger lehnt alg: none bei der Signaturprüfung grundsätzlich ab.

Starke Schlüssel verwenden

Bei HMAC (HS256, HS384, HS512) ist das Geheimnis der einzige Schutz. Ein kurzes oder ausgedachtes Passwort lässt sich offline durchprobieren, denn jedes abgefangene Token liefert alles, was für einen solchen Angriff nötig ist. Verwenden Sie für HS256 mindestens 256 Bit echten Zufall, zum Beispiel mit openssl rand -base64 32. Teilen sich mehrere Dienste ein Token, sind asymmetrische Verfahren (RS256, ES256, EdDSA) oft die bessere Wahl: Nur der Aussteller kennt den privaten Schlüssel, alle anderen prüfen mit dem öffentlichen.

kid, jku und x5u nicht blind vertrauen

Der Header kann angeben, mit welchem Schlüssel geprüft werden soll: kid als Kennung, jku oder x5u als URL, von der der Schlüssel geladen wird. Lädt Ihr Server Schlüssel von einer URL aus dem Token, kann ein Angreifer auf seinen eigenen Schlüssel verweisen. Verwenden Sie deshalb nur Schlüssel aus einer festen, vertrauenswürdigen Quelle (etwa einem fest konfigurierten JWKS-Endpunkt) und behandeln Sie kid wie jede andere Benutzereingabe – nicht ungeprüft in Dateipfade oder SQL-Abfragen einsetzen.

Claims prüfen

Eine gültige Signatur heißt nur, dass das Token von jemandem mit dem passenden Schlüssel stammt. Ob es für Sie und jetzt gilt, verraten die Claims:

  • exp (Ablaufzeit) und nbf (nicht vor): Zeitpunkte als Unix-Zeit in Sekunden. Abgelaufene oder noch nicht gültige Tokens ablehnen.
  • iat (ausgestellt am): hilfreich, um ein maximales Alter durchzusetzen; ein Wert in der Zukunft ist verdächtig.
  • iss (Aussteller): muss genau dem erwarteten Aussteller entsprechen.
  • aud (Empfänger): muss Ihren Dienst nennen. Sonst kann ein Token, das für eine andere Anwendung desselben Ausstellers gedacht war, bei Ihnen verwendet werden.

Uhrzeitabweichung: Die Uhren von Aussteller und Empfänger gehen selten exakt gleich. RFC 7519 erlaubt deshalb eine kleine Toleranz (Leeway) von meist höchstens wenigen Minuten; in der Praxis genügen oft 30 bis 60 Sekunden. Eine großzügigere Toleranz verlängert faktisch die Laufzeit jedes Tokens.

Laufzeit: Access-Tokens sollten kurz gültig sein – typisch sind wenige Minuten bis etwa eine Stunde. Ein Token, das ein Jahr lang gilt, ist im Grunde ein Passwort, das sich nicht ändern lässt. Im Beispiel oben liegen zwischen iat und exp 15 Minuten.

Unterscheiden sich Tokentypen (etwa Access-, Refresh- und ID-Token), sollten sie sich auch technisch unterscheiden lassen, zum Beispiel über einen eigenen typ im Header oder unterschiedliche aud-Werte. So kann ein Token nicht an einer Stelle eingesetzt werden, für die es nicht gedacht ist.

Was nicht ins Token gehört

Da jeder den Inhalt lesen kann, gehören keine vertraulichen Daten in die Payload: keine Passwörter oder Passwort-Hashes, keine Gesundheits- oder Zahlungsdaten, möglichst wenige personenbezogene Angaben wie E-Mail-Adresse oder Geburtsdatum. Tokens landen in Browser-Verläufen, Logdateien und Fehlermeldungen. Eine Nutzer-ID und die nötigen Berechtigungen reichen meist aus; weitere Daten lädt der Server bei Bedarf selbst.

Brauchen Sie tatsächlich vertrauliche Inhalte im Token, ist JWE der passende Weg. Beachten Sie auch: Ein echtes Token aus der Produktion sollten Sie nur in Werkzeuge einfügen, die es nicht weitergeben. Der JWT-Debugger arbeitet vollständig im Browser und überträgt nichts.

Speicherort im Browser

Wo eine Webanwendung das Token aufbewahrt, entscheidet darüber, welche Angriffe drohen:

SpeicherortVorteilRisiko
localStorage / sessionStorageeinfach, kein CSRF-Risikojedes eingeschleuste Skript (XSS) kann das Token auslesen und versenden
Cookie mit HttpOnly, Secure, SameSitefür JavaScript nicht lesbarBrowser sendet es automatisch mit – Schutz vor CSRF nötig
nur im Arbeitsspeichernach Schließen des Tabs weg, für XSS schwerer erreichbargeht beim Neuladen verloren, braucht meist ein Refresh-Token im Cookie

Für die meisten Webanwendungen ist ein HttpOnly-Cookie mit Secure und SameSite=Lax oder Strict die robusteste Wahl, ergänzt um CSRF-Schutz für ändernde Anfragen. Gegen XSS hilft kein Speicherort vollständig: Ein eingeschleustes Skript kann auch mit einem Cookie Anfragen im Namen des Nutzers stellen. XSS zu verhindern, etwa mit konsequenter Ausgabe-Kodierung und einer Content Security Policy, bleibt deshalb Pflicht.

Widerruf und Logout

Ein JWT ist bis zum Ablauf gültig – der Server muss sich dafür nichts merken. Das ist gerade der Vorteil, macht aber den Logout schwierig: Das Löschen im Browser entfernt nur die Kopie des Nutzers, nicht eine möglicherweise gestohlene. Bewährt haben sich:

  • Kurze Access-Tokens und Refresh-Tokens: Das Access-Token läuft nach wenigen Minuten ab. Ein langlebiges Refresh-Token, das der Server speichert und jederzeit widerrufen kann, holt ein neues.
  • Refresh-Token-Rotation: Bei jeder Verwendung gibt es ein neues Refresh-Token, das alte wird ungültig. Taucht ein bereits verwendetes Refresh-Token erneut auf, wurde es vermutlich gestohlen – dann widerrufen Sie alle Tokens dieser Sitzung.
  • Sperrliste: Für Notfälle können Sie die ID eines Tokens (jti) bis zu seinem Ablauf auf eine Sperrliste setzen. Das erfordert wieder eine Abfrage pro Anfrage, bleibt dank kurzer Laufzeiten aber klein.

Checkliste

  • Erlaubte Algorithmen auf dem Server fest vorgeben; alg: none immer ablehnen.
  • HMAC-Geheimnisse mit mindestens 256 Bit Zufall, nie ein ausgedachtes Passwort.
  • Schlüssel nur aus fester Quelle laden, kid, jku und x5u nicht blind folgen.
  • exp, nbf, iss und aud immer prüfen, Leeway klein halten.
  • Access-Tokens kurz gültig halten, Refresh-Tokens rotieren und widerrufbar speichern.
  • Keine vertraulichen Daten in die Payload – sie ist nur kodiert, nicht verschlüsselt.
  • Im Browser bevorzugt HttpOnly-Cookies mit Secure und SameSite, dazu CSRF-Schutz.
  • Eine gepflegte, verbreitete Bibliothek verwenden statt eigener Prüfcode.

Wenn Sie ein Token schnell untersuchen möchten, zeigt der JWT-Debugger Header, Payload und Ablaufzeit an und prüft die Signatur mit einem Geheimnis, einem öffentlichen Schlüssel oder einem JWKS.

Tools zum Thema

Weitere Anleitungen