JWT-Signatur prüfen: Warum die Verifizierung fehlschlägt

Inhalt
Wenn Sie die Signatur eines JWT verifizieren, können Sie prüfen, ob das Token noch exakt den Inhalt hat, den es bei der Ausstellung hatte, und ob die Signatur tatsächlich mit einem Secret Key erzeugt wurde, den Sie kennen. Dieser Beitrag richtet sich an Entwickler, die selbst nachprüfen möchten, ob ein Token aus einer API-Antwort manipuliert wurde.
Er erklärt anhand der tatsächlichen Abläufe im Code, wie die Signatur berechnet und verglichen wird – und welche zwei unterschiedlichen Ursachen hinter einer fehlgeschlagenen Verifizierung stecken können.
Kurzfassung ① Ein JWT ist eine Zeichenkette aus drei Teilen – header.payload.signature –, die durch Punkte getrennt sind. Header und Payload sind nicht verschlüsselt, sondern nur per Base64Url kodiert. ② Die Signatur ist der HMAC-SHA256-Wert der zusammengefügten Zeichenkette aus Header und Payload, berechnet mit dem Secret Key. Die Verifizierung wiederholt dieselbe Berechnung und vergleicht, ob beide Werte übereinstimmen. ③ Eine fehlgeschlagene Verifizierung sieht gleich aus, egal ob der Secret Key abweicht oder der Inhalt manipuliert wurde. Die Fehlermeldung allein verrät nicht, welcher der beiden Fälle vorliegt.
Verifizierung fehlgeschlagen: aber woran liegt es?
Es ist ein gängiges Muster: Ein Backend-API stellt beim Login ein JWT aus, und der Client schickt dieses Token bei jeder weiteren Anfrage im Authorization-Header mit. Bei jeder Anfrage berechnet der Server die Signatur des Tokens neu und prüft so, ob das Token wirklich von ihm ausgestellt wurde.
Kritisch wird es, wenn diese Prüfung fehlschlägt. Hat sich beim erneuten Deployment des Servers der Secret Key in der Umgebungsvariable geändert, oder wurde in der Testumgebung versehentlich ein anderer Key eingetragen, erscheint ebenfalls nur „fehlgeschlagen" – genau wie bei einem manipulierten Token. Wer das Prinzip nicht kennt, sucht die Ursache schnell an der falschen Stelle.
Ein weiteres verbreitetes Missverständnis lautet: „Die Nutzerdaten im Payload sind verschlüsselt und damit sicher." Tatsächlich ist der Payload lediglich per Base64Url kodiert. Wer die Token-Zeichenkette besitzt, kann den Inhalt lesen.
Aus diesem Irrtum entsteht mitunter der Fehler, sensible Daten wie Passwörter oder Ausweisnummern unverändert im Payload abzulegen.
Signatur ohne Tool selbst berechnen und verifizieren
Ein JWT besteht aus drei Teilen, die durch Punkte (.) getrennt sind. Die Reihenfolge ist header.payload.signature. Die Teile enthalten Folgendes:
- Header: JSON mit dem Signaturalgorithmus (alg) und dem Token-Typ (typ)
- Payload: JSON mit den eigentlichen Nutzdaten (Claims)
- Signature: der Wert, der aus der zusammengefügten Zeichenkette von Header und Payload mit dem Secret Key signiert wird
Header und Payload sind jeweils JSON, das per Base64Url kodiert wurde. Da es sich um eine Kodierung und nicht um eine Verschlüsselung handelt, kann jeder das ursprüngliche JSON ohne Schlüssel wiederherstellen.
Der Header-Teil eines HS256-Tokens, eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9, wird zum Beispiel wie folgt dekodiert:
{"alg":"HS256","typ":"JWT"}
Base64Url unterscheidet sich vom Standard-Base64 in zwei Zeichen: + wird zu -, / wird zu _, und das abschließende Padding mit = entfällt. Wenn Sie einen normalen Base64-Decoder verwenden wollen, müssen Sie diese beiden Zeichen zurücktauschen und das Padding ergänzen.
So verifizieren Sie die Signatur: Zuerst setzen Sie den Header-Teil und den Payload-Teil des Tokens wieder mit einem Punkt zu der Zeichenkette header.payload zusammen.
Berechnen Sie für diese Zeichenkette den HMAC-SHA256-Wert mit demselben Secret Key, der bei der Ausstellung verwendet wurde, und kodieren Sie ihn per Base64Url. Das Ergebnis muss exakt mit dem dritten Teil des Tokens übereinstimmen.
printf '%s' "$HEADER.$PAYLOAD" | openssl dgst -sha256 -hmac "geheimer-schluessel" -binary | openssl base64
Diese Berechnung ist deterministisch: Dieselbe Zeichenkette und derselbe Schlüssel ergeben immer dieselbe Signatur.
Ändern Sie nur ein einziges Zeichen in Header oder Payload, ergibt die neu berechnete Signatur einen völlig anderen Wert und stimmt nicht mehr mit der ursprünglichen überein. Die „Erkennung von Manipulation" beruht in der Praxis allein auf diesem einen Vergleich.
Von Hand passieren leicht Fehler: beim Ersetzen der Zeichen zwischen Base64 und Base64Url, beim Wiederherstellen des weggelassenen Paddings und bei der Syntax des HMAC-Befehls. Außerdem ist es mühsam, diese Schritte jedes Mal zu wiederholen.
Probieren Sie es mit unserem Tool „JWT erstellen und prüfen" aus.
Die Signatur wird direkt im Browser berechnet und verglichen. Geheimer Schlüssel und Token werden nicht an einen Server übertragen.

Zwei Ursachen für fehlgeschlagene Verifizierung: und die Verwechslung von Kodierung und Verschlüsselung
Hinter dem einen Ergebnis „Verifizierung fehlgeschlagen" stecken zwei verschiedene Ursachen. Weicht die neu berechnete Signatur von der Signatur im Token ab, wird unabhängig vom Grund immer nur „fehlgeschlagen" angezeigt.
| Ursache | Was ist anders? | So prüfen Sie es |
|---|---|---|
| Secret Key stimmt nicht überein | Der Schlüssel für die Signaturberechnung unterscheidet sich von dem bei der Ausstellung | Erneut abgleichen, ob die Zeichenkette exakt dem Key des ausstellenden Servers entspricht (einschließlich Leerzeichen und Zeilenumbrüchen) |
| Inhalt manipuliert | Ein JSON-Wert in Header oder Payload wurde nach der Ausstellung verändert | Schlägt die Prüfung trotz desselben Keys wie bei der Ausstellung fehl, wurde der Inhalt verändert |
Die Fehlermeldung selbst unterscheidet die beiden Ursachen also nicht. Erst wenn Sie sicher wissen, dass Sie den richtigen Key verwenden, und die Prüfung trotzdem fehlschlägt, können Sie darauf schließen, dass der Inhalt verändert wurde.
Das zweite Missverständnis ist die Annahme, der Payload sei verschlüsselt. Kodierung und Verschlüsselung verfolgen grundlegend verschiedene Ziele.
| Merkmal | Base64Url-Kodierung (JWT-Payload) | Verschlüsselung |
|---|---|---|
| Zweck | Daten als Text darstellen | Inhalt vor Dritten verbergen |
| Schlüssel zur Wiederherstellung nötig? | Nein | Ja |
| Wer kann das Original wiederherstellen? | Jeder, der die Token-Zeichenkette hat | Nur, wer den richtigen Entschlüsselungsschlüssel besitzt |
Die Signatur (signature) garantiert Integrität (keine Veränderung seit der Ausstellung) und Herkunft des Ausstellers (erstellt von jemandem, der den Secret Key kennt). Vertraulichkeit (Verbergen des Inhalts) garantiert sie nicht.
Die Werte im Payload kann jeder, der das Token besitzt, dekodieren und lesen – unabhängig davon, ob die Signatur gültig ist.
Zusammenfassung
- Ein JWT ist eine Zeichenkette aus drei Teilen – header.payload.signature –, die durch Punkte getrennt sind.
- Header und Payload sind nur per Base64Url kodiert, also kann jeder sie dekodieren und lesen. Es handelt sich nicht um Verschlüsselung.
- Die Signatur ist der HMAC-SHA256-Wert der Zeichenkette header.payload, berechnet mit dem Secret Key. Die Verifizierung wiederholt diese Berechnung und vergleicht, ob die Werte übereinstimmen.
- „Verifizierung fehlgeschlagen" erscheint gleichermaßen bei abweichendem Secret Key und bei manipuliertem Inhalt. Die Meldung allein unterscheidet die Fälle nicht.
- Die Signatur dient der Integrität und der Prüfung des Ausstellers, nicht dem Verbergen des Payloads.
Die Signatur wird direkt im Browser berechnet und verglichen. Geheimer Schlüssel und Token werden nicht an einen Server übertragen.
Häufig gestellte Fragen
Kann man den Payload eines JWT ohne Entschlüsselung einfach lesen?
Ja, es genügt, ihn zu dekodieren. Header und Payload sind per Base64Url kodiert, daher kann jeder das ursprüngliche JSON ohne Schlüssel wiederherstellen. Auch der Verifizierungs-Tab dieses Tools zeigt das dekodierte JSON immer mit an – unabhängig davon, ob die Signatur stimmt.
Heißt eine fehlgeschlagene Verifizierung immer, dass das Token gefälscht ist?
Nein. Ein Fehlschlag erscheint genauso, wenn der Secret Key, mit dem Sie prüfen, vom Key bei der Ausstellung abweicht. Schlägt die Prüfung fehl, obwohl Sie exakt dieselbe Zeichenkette wie der ausstellende Server verwenden, sollten Sie als Nächstes prüfen, ob der Inhalt verändert wurde.
Kann ich auch Tokens verifizieren, die mit asymmetrischen Algorithmen wie RSA signiert wurden?
Dieses Tool unterstützt nur die symmetrische Signatur mit HMAC-SHA256 (HS256). Tokens, die mit asymmetrischen Algorithmen wie RSA (z. B. RS256) signiert wurden, lassen sich mit diesem Tool nicht verifizieren.
Werden der Secret Key oder das Token, die ich in dieses Tool eingebe, an einen Server übertragen?
Nein. Signatur und Verifizierung werden mit der Web Crypto API des Browsers ausschließlich auf Ihrem Gerät berechnet. Die eingegebenen Werte verlassen Ihr Gerät nicht.
Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen