Lösung für "JWT expired" und häufige JSON Web Token Fehler: Ein vollständiger Leitfaden

JSON Web Tokens (JWT) sind der Industriestandard für die sichere Übertragung von Informationen zwischen Parteien als JSON-Objekt. Sie werden häufig für die Authentifizierung und Autorisierung in modernen Web- und Mobilanwendungen eingesetzt. Da sie jedoch kryptografisch signiert sind und oft strenge Ablaufregeln haben, können sie eine große Quelle für Debugging-Kopfschmerzen sein.

In diesem Leitfaden werden wir die häufigsten JWT-Fehler aufschlüsseln, erklären, warum sie auftreten, und Ihnen zeigen, wie Sie diese beheben können.

1. Häufige JWT-Fehlermeldungen

Abhängig von der verwendeten Bibliothek (wie jsonwebtoken in Node.js) werden Ihnen diese häufigen Fehlernamen begegnen:

TokenExpiredError: Das Token ist gültig, aber seine Ablaufzeit ist überschritten.
JsonWebTokenError: invalid signature: Die Signatur des Tokens stimmt nicht mit dem angegebenen Geheimnis/Schlüssel überein.
JsonWebTokenError: jwt malformed: Der angegebene String ist keine gültige JWT-Struktur.
JsonWebTokenError: jwt signature is required: Ein Token wurde ohne Signaturabschnitt bereitgestellt.
JsonWebTokenError: jwt invalid audience: Der aud-Claim im Token stimmt nicht mit dem erwarteten Wert überein.

2. Hauptursachen und Lösungen

2.1 "TokenExpiredError" (JWT expired)

Jedes sichere JWT sollte einen exp (Expiration) Claim haben. Sobald die aktuelle Zeit diesen Wert überschreitet, ist das Token nicht mehr gültig.

Das Symptom: Benutzer werden plötzlich abgemeldet, oder API-Anfragen geben 401 Unauthorized-Fehler mit der Nachricht jwt expired zurück.

Die Lösung:

Refresh Tokens: Implementieren Sie eine "Refresh Token"-Strategie, damit sich Benutzer nicht jedes Mal manuell anmelden müssen, wenn ein Access Token abläuft.
Uhrzeitsynchronisation: Stellen Sie sicher, dass die Uhr Ihres Servers mittels NTP synchronisiert ist. Schon eine Abweichung von wenigen Sekunden kann Probleme verursachen.
Prüfen Sie iat und nbf: Stellen Sie sicher, dass auch die Claims "ausgestellt am" (iat) und "nicht vor" (nbf) korrekt sind.

2.2 "invalid signature" (invalid JWT signature)

Ein JWT besteht aus drei Teilen: Header, Payload und Signatur. Die Signatur wird durch Hashen von Header und Payload mit einem geheimen Schlüssel erstellt. Wenn sich auch nur ein Zeichen in der Payload ändert oder der falsche geheime Schlüssel verwendet wird, wird die Signatur ungültig.

Die Ursache:

Verwendung des falschen secret oder public key zur Verifizierung des Tokens.
Eine Diskrepanz zwischen dem zum Signieren verwendeten Algorithmus (z. B. HS256) und dem zur Verifizierung verwendeten Algorithmus (z. B. RS256).
Das Token wurde manipuliert oder während der Übertragung beschädigt.

Die Lösung:

Überprüfen Sie Ihre Umgebungsvariablen für den geheimen Schlüssel doppelt.
Stellen Sie sicher, dass der alg-Header im JWT mit dem Algorithmus übereinstimmt, den Sie zur Verifizierung verwenden.

2.3 "jwt malformed" oder "jwt decode failed"

Ein gültiges JWT muss aus drei durch Punkte getrennten Teilen bestehen (header.payload.signature). Wenn ein Teil fehlt oder der String kein gültiges Base64URL ist, gilt er als fehlerhaft (malformed).

Die Ursache:

Übergabe eines "Bearer "-Präfixes direkt an die Bibliothek (z. B. atob("Bearer <token>")).
Kopieren und Einfügen eines unvollständigen Tokens.
Zusätzliche Leerzeichen oder versteckte Zeichen im Token-String.

Die Lösung: Stellen Sie sicher, dass Sie das Bearer -Präfix entfernen, bevor Sie es an Ihren Decoder übergeben.

const token = authHeader.split(' ')[1]; // Extrahiere Token aus "Bearer <token>"

2.4 "jwt invalid audience" oder "jwt invalid issuer"

Diese Fehler treten auf, wenn die Claims aud (Audience) oder iss (Issuer) in der Payload nicht mit den Werten übereinstimmen, die Ihr Server erwartet.

Die Lösung: Stellen Sie sicher, dass die Konfiguration auf Ihrem Authentifizierungsserver (z. B. Auth0, Firebase oder Ihr eigener) mit den Verifizierungsoptionen in Ihrem Anwendungscode übereinstimmt.

3. Fortgeschrittene Fehlerbehebung

3.1 Payload inspizieren

Wenn Sie einen Signaturfehler erhalten, besteht der erste Schritt darin, die Payload zu inspizieren, um zu sehen, ob sie die erwarteten Daten enthält. Sie benötigen keinen geheimen Schlüssel, um die Payload zu dekodieren und zu lesen (da sie lediglich Base64-kodiert ist).

3.2 Algorithm Confusion Attacks

Stellen Sie sicher, dass Ihre Bibliothek so konfiguriert ist, dass sie nur die spezifischen Algorithmen zulässt, die Sie erwarten. Einige ältere Bibliotheken waren anfällig für einen Angriff, bei dem ein Angreifer den Header auf alg: none ändern konnte, um die Sicherheit zu umgehen. Moderne Bibliotheken haben dies größtenteils behoben, aber definieren Sie Ihre erlaubten Algorithmen immer explizit.

jwt.verify(token, secret, { algorithms: ['HS256'] });

4. Prävention und Best Practices

Kurzlebige Access Tokens: Halten Sie Access Tokens kurzlebig (z. B. 15 Minuten) und verwenden Sie Refresh Tokens für längere Sitzungen.
Sichere Geheimnisse: Schreiben Sie Ihr JWT-Geheimnis niemals direkt in den Code. Verwenden Sie Umgebungsvariablen und rotieren Sie diese regelmäßig.
Jede Anfrage validieren: Vertrauen Sie niemals einem JWT, ohne dessen Signatur serverseitig zu verifizieren.
HTTPS verwenden: Übertragen Sie Tokens immer über HTTPS, um "Man-in-the-Middle"-Angriffe zu verhindern.

5. FAQ: Häufig gestellte Fragen

F: Kann ich die Daten in einem JWT ohne das Geheimnis lesen?

A: Ja. Header und Payload sind lediglich Base64URL-kodiert, nicht verschlüsselt. Jeder, der das Token hat, kann die Daten lesen. Geben Sie niemals sensible Informationen wie Passwörter oder Kreditkartennummern in eine JWT-Payload ein.

F: Was ist der Unterschied zwischen HS256 und RS256?

A: HS256 verwendet einen einzelnen geheimen Schlüssel sowohl zum Signieren als auch zum Verifizieren (symmetrisch). RS256 verwendet einen privaten Schlüssel zum Signieren und einen öffentlichen Schlüssel zum Verifizieren (asymmetrisch), was für verteilte Systeme sicherer ist.

F: Wie gehe ich mit einem "jwt expired" Fehler im Frontend um?

A: Fangen Sie den 401-Fehler in Ihrem API-Interceptor ab. Wenn der Fehler "jwt expired" lautet, versuchen Sie, Ihren "Refresh Token"-Endpunkt aufzurufen. Wenn dies fehlschlägt, leiten Sie den Benutzer zur Login-Seite weiter.

6. Schnell-Check-Tool

Haben Sie Probleme mit einem bestimmten Token? Nutzen Sie unseren JWT Decoder & Debugger. Er ermöglicht Ihnen:

Sofortiges Dekodieren jedes JWT, um Header und Payload zu sehen.
Überprüfung des Ablaufstatus und von Claims wie iat, exp und nbf.
Identifizierung fehlerhafter Tokens (malformed tokens) und Kodierungsproblemen.
Validierung von Signaturen (wenn Sie Ihren geheimen Schlüssel lokal angeben).

Lösung für 'JWT expired' und häufige JSON Web Token Fehler