JWT erklärt: JSON Web Tokens dekodieren und debuggen

Was ein JWT wirklich ist

Ein JSON Web Token ist eine Zeichenkette. Darin liegt der ganze Trick. Statt dem Client eine Session-ID zu geben und die Sitzung auf dem Server zu halten, gibt man ihm eine signierte Aussage — „das ist Nutzer 4821, das sind seine Rechte, das läuft um 14:05 ab“ — und lässt ihn sie tragen. Jeder Dienst, der dem Signaturschlüssel vertraut, kann die Aussage lesen und handeln, ohne eine Datenbank zu fragen.

Das macht JWTs sehr bequem und etwas gefährlich, aus demselben Grund: die Daten liegen in der Hand des Clients. Ein Token, das Sie ausstellen, kann jeder lesen, der es hat, lässt sich vor dem Ablauf nicht zurückziehen und wird von allem akzeptiert, was der Signatur vertraut. Fast alle JWT-Probleme in Produktion entstehen daraus, eine dieser drei Tatsachen zu vergessen.

Ein Token sieht aus wie drei Blöcke Kauderwelsch, durch Punkte getrennt:

eyJhbGciOiJIUzI1NiIsImtpZCI6ImtleS0yIn0.eyJzdWIiOiI0ODIxIiwiZXhwIjoxNzY1MTExMTExfQ.3xS7_c9Nn-aQ

Es ist nicht verschlüsselt. Die ersten beiden Blöcke sind schlichtes JSON in Base64url, einem URL-sicheren Alphabet, das + und / durch - und _ ersetzt und das abschließende =-Padding weglässt. Jeder kann sie in einer Sekunde wieder in JSON verwandeln — genau das tut ein JWT Decoder.

Die drei Teile und was jeder davon tut

Trennen Sie das Token an den Punkten, und Sie haben Header, Payload und Signatur.

Der Header

Klein, und fast immer eine Frage von Schlüsseln. alg nennt den Signatur-Algorithmus, typ ist meist JWT, und kid ist eine Key-ID, die dem Prüfer sagt, welchen öffentlichen Schlüssel er holen soll, wenn der Aussteller mehr als einen hat. Wenn ein Token nach einer Schlüsselrotation plötzlich nicht mehr validiert, schauen Sie zuerst auf kid.

Die Payload

Die Claims: die eigentliche Aussage. Einige sind in der Spezifikation registriert (iss, sub, aud, exp, nbf, iat, jti), der Rest ist, was Ihr Aussteller hinzufügen wollte: scope, roles, tenant_id, eine E-Mail-Adresse, ein Feature-Flag.

Die Signatur

Ein MAC oder eine digitale Signatur über die ersten beiden Teile, genau so, wie sie in der Zeichenkette stehen. Dieses Detail ist wichtig: die Signatur deckt die kodierten Bytes ab. Das JSON neu zu serialisieren und neu zu kodieren ergibt also ein Token, das nicht mehr validiert, selbst wenn die Daten identisch sind. Bauen Sie ein Token nie neu, um es „aufzuräumen“.

Wie man ein Token dekodiert und worauf man zuerst schaut

Fügen Sie die ganze Zeichenkette in einen Decoder ein, Punkte inklusive. Wenn Sie sie aus einem Request kopiert haben, entfernen Sie das Präfix Bearer — oder nehmen Sie ein Werkzeug, das das für Sie tut. Dann lesen Sie in dieser Reihenfolge:

1. Hat es überhaupt dekodiert? Sagt der Decoder, die Teile seien kein gültiges Base64url-JSON, kam das Token abgeschnitten oder verstümmelt an. Ein Cookie, das an eine Größengrenze gestoßen ist, und ein umgebrochener Header sehen beide so aus.
2. exp. Der Ablauf erklärt die Mehrheit aller „vor fünf Minuten ging es noch“-Meldungen und ist das Erste, was man ausschließt.
3. aud und iss. Ein Token für eine andere Audience ist ein völlig gültiges Token, das Ihre API zu Recht ablehnt.
4. Die eigenen Claims. Erst wenn die Standard-Claims stimmen, lohnt der Streit darüber, ob scope das Erwartete enthält.

Dekodieren Sie lokal, wo Sie können. Ein Token ist eine gültige Zugangsberechtigung; es auf einer beliebigen Website einzufügen ist derselbe Fehlertyp wie ein eingefügtes Passwort. Jedes brauchbare Werkzeug dekodiert im Browser und schickt nichts irgendwohin.

Die Claims, die entscheiden, ob ein Token funktioniert

Fünf Claims leisten fast die ganze Arbeit, und jeder kann eine Anfrage allein ablehnen.

• exp — Ablauf, als Unix-Zeitstempel in Sekunden. Ein Millisekundenwert hier ist ein Klassiker: er landet im Jahr 57000 und das Token läuft nie ab. Ein guter Decoder zeigt beides, das echte Datum und wie lange es her ist.
• nbf — not before. Bis zu diesem Moment ist das Token ungültig. Selten absichtlich genutzt, gelegentlich versehentlich gesetzt auf einer Maschine mit vorlaufender Uhr.
• iat — ausgestellt am. Nützlich, um technisch nicht abgelaufene, aber verdächtig alte Tokens abzulehnen, und um ein Uhrproblem zu erkennen, wenn iat in der Zukunft liegt.
• aud — Audience, der vorgesehene Empfänger. Eine API, die diese Prüfung überspringt, nimmt bereitwillig ein Token an, das Ihr anderer Dienst für sich selbst ausgestellt hat — ein echter Weg zur Rechteausweitung zwischen Microservices.
• iss — Aussteller. Pinnen Sie ihn auf genau den erwarteten Aussteller und holen Sie Schlüssel nur aus dessen veröffentlichtem Schlüsselsatz.

jti ist der Sonderfall: eine eindeutige Token-ID. Sie bedeutet nur etwas, wenn Sie sie speichern und prüfen, aber sie macht den Widerruf eines einzelnen Tokens überhaupt erst möglich.

Dekodieren ist nicht Verifizieren

Das ist der Punkt, der Leute erwischt. Dekodieren liest Base64url und zeigt Ihnen JSON. Es sagt Ihnen, was ein Token behauptet. Es sagt nichts darüber, ob die Behauptung wahr ist.

Jeder kann {"sub":"1","role":"admin"} schreiben, es in Base64url packen, irgendeine Zeichenkette als Signatur anhängen und es Ihnen geben. Es dekodiert in jedem Decoder einwandfrei, auch in unserem. Was es scheitern lässt, ist die Verifikation: die Signatur mit dem Schlüssel des Ausstellers neu berechnen und das Token verwerfen, wenn sie nicht passt. Dieser Schritt braucht ein Secret oder einen öffentlichen Schlüssel, er gehört auf Ihren Server, und kein Browser-Werkzeug kann ihn für Sie erledigen.

Behandeln Sie einen Decoder also als Anzeige, nie als Beweis. „Ich habe es dekodiert und da steht admin“ ist kein Sicherheitsbefund. „Mein Server hat es verifiziert und da steht admin“ schon.

Warum ein gültig aussehendes Token einen 401 bekommt

Wenn das Token sauber dekodiert und die API es dennoch ablehnt, ist es fast immer eines davon:

• Abgelaufen. Prüfen Sie exp gegen die Uhr des Servers, nicht gegen Ihre.
• Uhrabweichung. Ein Server, der zwei Minuten vorgeht, lehnt gerade ausgestellte Tokens ab. Die meisten Bibliotheken erlauben genau deshalb eine kleine Toleranz; steht sie bei Ihnen auf null, lohnt ein zweiter Blick.
• Falsche Audience. Häufig, wenn ein Identity-Provider mehrere APIs bedient.
• Schlüsselrotation. Der Aussteller hat mit einem neuen Schlüssel signiert, der Prüfer hat noch den alten Satz im Cache, und kid löst nicht mehr auf.
• Das Token kam nie an. Ein fehlender oder fehlerhafter Authorization-Header, ein verlorenes Cookie oder ein Proxy, der Header entfernt. Prüfen Sie, was der Server wirklich erhalten hat, bevor Sie das Token beschuldigen: die HTTP-Statuscode-Abfrage und unser Leitfaden zu Statuscodes helfen, 401 von einem 403 zu unterscheiden, der etwas völlig anderes bedeutet.

401 oder 403?

Ein 401 heißt: die Berechtigung fehlt, ist abgelaufen oder nicht prüfbar — reparieren Sie das Token. Ein 403 heißt: die Berechtigung war in Ordnung und die Antwort bleibt nein — reparieren Sie die Rechte oder den Claim scope. Dienste, die bei einem Autorisierungsfehler 401 liefern, schicken Leute dazu, ein Token zu debuggen, das nie das Problem war.

Den Signatur-Algorithmus wählen und prüfen

In der Praxis zählen zwei Familien. HS256 ist ein HMAC mit gemeinsamem Secret: wer prüfen kann, kann auch signieren — innerhalb eines Dienstes in Ordnung, über Organisationsgrenzen hinweg schlecht. RS256 und ES256 signieren mit einem privaten und prüfen mit einem öffentlichen Schlüssel, sodass eine API Tokens validieren kann, die sie selbst nie hätte ausstellen können.

Dann gibt es alg: none, ein unsigniertes Token, das die Spezifikation erlaubt und das Sie nie akzeptieren sollten. Es steht im Standard, also stand es in Bibliotheken, also wurde es ausgenutzt: einem Prüfer, der den Algorithmus aus dem Header des Tokens selbst nimmt, kann man sagen „dieses ist unsigniert, vertrau einfach“. Ein verwandter Trick übergibt einem RS256-Prüfer ein HS256-Token, das mit dem öffentlichen Schlüssel als HMAC-Secret signiert wurde.

Die Verteidigung ist eine Zeile Policy: entscheiden Sie, welche Algorithmen Sie akzeptieren, bevor Sie das Token ansehen, und lehnen Sie alles andere ab. Der Header ist ein Hinweis darauf, welchen Schlüssel man nimmt, keine Anweisung, ob man die Signatur prüft. Wenn Ihr Decoder alg: none rot markiert, ist das der Grund.

Was nie in eine Payload gehört

Weil die Payload kodiert und nicht verschlüsselt ist, ist jeder Claim öffentlich für jeden, der das Token hat — und Tokens landen im Browser-Speicher, in Logs, in Error-Trackern, in Support-Tickets und auf Screenshots. Halten Sie aus der Payload heraus:

• Alles, was Sie nicht in eine URL schreiben würden: Passwörter, API-Keys, Kartennummern, Gesundheitsdaten.
• Interne Identifier, die Sie nicht veröffentlichen wollen: Datenbank-Primärschlüssel, interne Hostnamen, Lizenzkonditionen.
• Große Blobs. Jeder Request trägt das Token; ein Kilobyte Claims ist ein Kilobyte pro Aufruf, und übergroße Tokens sind ein verlässlicher Weg, die Header-Größengrenzen eines Proxys zu reißen.

Halten Sie Tokens auch aus URLs heraus. Ein Token im Query-String landet in Server-Logs, in Referer-Headern und im Browserverlauf. Schicken Sie es im Authorization-Header und sorgen Sie dafür, dass Ihre Seite eine sinnvolle Referrer-Policy setzt: unser Leitfaden zu Sicherheits-Headern behandelt das, und der Sicherheits-Header-Prüfer sagt Ihnen, was Sie heute senden.

Ablauf, Refresh und das Widerrufsproblem

Ein JWT lässt sich nicht zurückrufen. Einmal ausgestellt, gilt es bis exp, egal was mit dem Konto dahinter passiert. Deaktivieren Sie einen Nutzer, und sein Access-Token funktioniert weiter, bis es ausläuft. Das ist der Preis dafür, nicht bei jedem Request eine Datenbank zu fragen.

Die Standardantwort sind zwei Tokens. Ein kurzlebiges Access-Token — Minuten, nicht Tage — trägt die Claims und macht die Arbeit. Ein langlebiges Refresh-Token liegt serverseitig, wird bei jeder Nutzung gegen eine Datenbank geprüft und kann sofort widerrufen werden. Jemanden abzumelden heißt dann: das Refresh-Token entwerten und das kurze Fenster abwarten, bis das Access-Token von selbst stirbt.

Wählen Sie das Ablauffenster bewusst: es ist die Lücke zwischen dem Entzug des Zugriffs und dem tatsächlichen Ende des Zugriffs. Fünfzehn Minuten sind ein verbreiteter Kompromiss. Stunden sind schwer zu rechtfertigen; Tage heißen, dass Sie gar keinen Widerruf haben. Und wenn Sie sofortigen Widerruf brauchen, führen Sie eine Sperrliste von jti-Werten — womit Sie wieder bei jedem Request einen Speicher abfragen und eine schlichte Session vielleicht das einfachere Design ist.

Was Sie auch wählen, die Debug-Schleife ist dieselbe: Token dekodieren, exp und aud lesen, die Uhr bestätigen, dann die Signatur auf dem Server verifizieren. Vier Schritte, in dieser Reihenfolge, und fast jedes Token-Problem fällt in den ersten zwei heraus.

Verwandte Tools und Leitfäden:

• JWT Decoder – Dekodieren Sie ein JSON Web Token und lesen Sie Header, Payload, Claims und Ablauf.
• Base64-Encoder & -Decoder – Text in Base64 kodieren oder zurück, mit URL-safe-Ausgabe und korrektem UTF-8.
• Base64 erklärt: wie Kodieren und Dekodieren wirklich funktionieren – Wie Base64 Bytes in Text verwandelt

Häufige Fragen