JWT-Debugging: Häufige Probleme und Lösungen

Warum JWTs brechen und wo Sie suchen

JWT-basierte Authentifizierung scheitert auf eine Handvoll wiederkehrender Arten: abgelaufene Tokens, Uhr-Drift, falscher Issuer oder Audience, Algorithmus-Verwirrung und Signaturprüfungsfehler.

Fast alle hinterlassen eine lesbare Spur. Ein JWT ist nicht undurchsichtig – Header und Payload sind Base64URL-kodiertes JSON, das jede Person dekodieren kann. Die Claims sagen, was das Token behauptet; der Fehler Ihres Servers sagt, was es abgelehnt hat.

Dieser Leitfaden führt vom Token selbst zur Bibliothekskonfiguration und zeigt, wie Sie dabei verhindern, dass das Token an eine beliebige Website leakt.

JWT-Anatomie: drei Segmente, eine Signatur

Ein JWT besteht aus drei durch Punkte getrennten Segmenten: header.payload.signature.

Der Header deklariert Algorithmus (alg) und Token-Typ (typ). Die Payload enthält Claims – Aussagen über das Subject und das Token selbst. Beide sind schlichtes JSON, Base64URL-kodiert und für jede Person lesbar.

Die Signatur wird mit dem Algorithmus aus dem Header und einem vom Issuer gehaltenen Schlüssel erzeugt. Sie erlaubt einem Prüfer, zu bestätigen, dass das Token nicht verändert und vom erwarteten Herausgeber signiert wurde.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
# header    = {"alg":"HS256","typ":"JWT"}
# payload   = {"sub":"1234567890","name":"John Doe","iat":1516239022}
# signature = HMAC-SHA256(header.payload, secret)

Die Standard-Claims und ihre Bedeutung

Ein sicherer Debugging-Ablauf

1. Kopieren Sie das vollständige JWT aus Log, Header oder fehlgeschlagener Anfrage – beide Punkte eingeschlossen.
2. Dekodieren Sie es lokal mit dem JWT-Dekoder – fügen Sie Produktions-Tokens niemals in ein ungeprüftes Online-Werkzeug ein.
3. Lesen Sie die Payload-Claims: exp, iat, nbf, iss, aud, sub.
4. Rechnen Sie exp in eine lesbare Zeit um und vergleichen Sie mit der aktuellen Serverzeit, nicht mit Ihrer Laptop-Zeit.
5. Prüfen Sie iss und aud gegen das, was Ihre API zu akzeptieren konfiguriert ist.
6. Sehen die Claims korrekt aus, liegt der Fehler in der Verifikation: Algorithmus, Schlüssel oder Uhrzeitbehandlung in der Bibliothek.
7. Redigieren Sie das Token, bevor Sie Logs mit anderen teilen – auch intern.

Häufige Fehlermuster und Lösungen

Dekodieren ist nicht Verifizieren

Dekodieren liest die Claims – jedes Werkzeug kann das, kein Schlüssel nötig. Verifizieren beweist, dass das Token authentisch ist: Signatur, exp, nbf, iss, aud und Algorithmus, geprüft vom Server mit dem richtigen Schlüssel.

Debugging beginnt meist mit dem Dekodieren, um das Token zu verstehen, und geht dann zur Verifikation über, um zu verstehen, warum der Server es ablehnte.

Seien Sie vorsichtig mit Dekoder-Diensten, die behaupten, Signaturen zu prüfen: Echte Verifikation erfordert den Signaturschlüssel oder öffentlichen Schlüssel, den ein entfernter Dienst niemals von Ihnen verlangen sollte. Ein clientseitiges Werkzeug ist der sichere Standard.

Debugging-Werkzeuge über den Dekoder hinaus

• Ein clientseitiger JWT-Dekoder, um Claims ohne Upload zu lesen
• Der Zeitstempel-Konverter, um exp/iat-Unix-Sekunden in lesbare Daten umzuwandeln
• Ein Base64/Base64URL-Dekoder zur Prüfung einzelner Segmente
• Die JWT-Bibliothek Ihrer Sprache mit aktivierter Signaturprüfung und fixiertem Algorithmus
• Strukturierte Anfrageprotokollierung, die Authorization-Header standardmäßig maskiert

FAQ

Referenzen

• RFC 7519 – JSON Web Token (JWT): https://www.rfc-editor.org/rfc/rfc7519
• RFC 7515 – JSON Web Signature (JWS): https://www.rfc-editor.org/rfc/rfc7515
• RFC 7517 – JSON Web Key (JWK): https://www.rfc-editor.org/rfc/rfc7517
• OWASP JWT Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html