JWT-Decoder: JSON Web Tokens lesen, Ablauf prüfen und Signatur verifizieren

Ein Benutzer kommt nach dem Single Sign-on nicht in die Anwendung, ein API-Aufruf liefert „401 Unauthorized“, ein Reverse-Proxy lehnt Anfragen ab: In vielen dieser Fälle steckt die Ursache in einem JSON Web Token. Mal ist es abgelaufen, mal fehlt die richtige Zielgruppe, mal passt der Schlüssel nicht zur Signatur. Der JWT-Decoder auf s-edv.com macht Header und Claims lesbar, zeigt den Ablaufstatus in Ihrer Ortszeit und prüft auf Wunsch die Signatur mit Secret oder öffentlichem Schlüssel. Diese Anleitung richtet sich an Admins, die Keycloak, Authentik, Zitadel oder eigene APIs betreuen und Anmeldeprobleme schnell eingrenzen möchten.

Voraussetzungen

• Ein aktueller Browser mit JavaScript. Die Signaturprüfung nutzt die Web Crypto API des Browsers.
• Ein Token zum Untersuchen, etwa aus dem Netzwerk-Tab der Entwicklerwerkzeuge (Header Authorization: Bearer …), aus einem Log oder aus der Testumgebung Ihres Identity Providers.
• Für die Signaturprüfung das Secret (HS-Verfahren) oder den öffentlichen Schlüssel des Ausstellers. Bei OpenID Connect finden Sie die Schlüssel unter der jwks_uri aus /.well-known/openid-configuration.
• Für die Gegenprobe ein Linux-Terminal mit base64, openssl und python3. Ein separates Werkzeug wie jq ist nicht nötig.
• Grundwissen zu OAuth 2.0 oder OpenID Connect ist hilfreich, aber nicht Bedingung.

Für den Betrieb eines eigenen Identity Providers wie Keycloak oder Pocket ID genügt für kleine Teams ein Server mit 2 Kernen und 4 GB RAM.

Schritt 1: Den Aufbau eines JWT verstehen und das Tool öffnen

Ein JSON Web Token (RFC 7519) besteht aus drei Teilen, getrennt durch Punkte: Header, Payload und Signatur. Header und Payload sind JSON-Objekte in Base64url-Kodierung, also Base64 mit - und _ statt + und / und ohne Füllzeichen. Kodieren ist kein Verschlüsseln: Jeder, der das Token sieht, kann den Inhalt lesen. Die Signatur verhindert nur, dass jemand den Inhalt unbemerkt ändert.

Öffnen Sie den JWT-Decoder. Oben steht der Bereich „Token“ mit den Schaltflächen „Kopieren“ und „Leeren“, darunter drei Vorlagen: „Beispiel HS256“, „Abgelaufenes Token“ und „Unsigniert (alg: none)“. Es folgen „Signatur prüfen“ sowie die Blöcke „Header“, „Payload“ und „Claims“. Laut Seite sind die HS256-Beispiele mit dem Demo-Secret s-edv-demo-secret-nur-zum-ausprobieren signiert, das beim Laden automatisch eingetragen wird.

Die Seite gibt an, dass Token, Secret und Schlüssel im Browser bleiben. Im Test luden wir die Seite, spielten alle Vorlagen und eigene Tokens durch und zählten die Netzwerkanfragen: Nach dem Laden der Tool-Skripte kam keine weitere Anfrage hinzu.

Verifizieren: Klicken Sie „Beispiel HS256“. Das Token erscheint farbig in Header, Payload und Signatur gegliedert, darunter „Gültig bis Di., 01.01.2030, 01:00:00 Uhr“ und unter „Signatur prüfen“ die Meldung „Signatur gültig“ mit „HS256 · Secret mit 38 Byte“. Das Demo-Secret hat tatsächlich 38 Zeichen.

Schritt 2: Token einfügen und Claims lesen

Fügen Sie Ihr Token in das Feld „JSON Web Token einfügen“ ein. Kopieren Sie es ruhig samt „Bearer“ aus einem HTTP-Header, das Tool entfernt das Präfix und meldet „Präfix „Bearer“ entfernt.“ Header und Payload erscheinen formatiert als JSON, jeweils mit „Kopieren“.

Die Tabelle „Claims“ listet jeden Eintrag mit Wert und Bedeutung auf. Die wichtigsten Standard-Claims:

• iss Aussteller, meist die Adresse des Identity Providers,
• sub Subjekt, die eindeutige ID des Benutzers oder Dienstes,
• aud Zielgruppe, der Empfänger muss sich darin wiederfinden,
• exp, nbf, iat Ablauf, gültig ab und Ausstellung als Unix-Zeitstempel,
• jti eine eindeutige Token-ID, etwa für Sperrlisten.

Zeitangaben übersetzt das Tool in Ihre Ortszeit, im Test „Europe/Berlin“, und zeigt zusätzlich die relative Zeit, den Rohwert und ISO 8601 in UTC. Eigene Claims, etwa admin, kennzeichnet es als „Eigenes Claim des Ausstellers“. Bei Keycloak finden Sie so zum Beispiel die Rollen unter realm_access.

Verifizieren: Rechnen Sie einen Zeitstempel im Terminal nach. Für das Beispiel-Token zeigte das Tool bei iat „Do., 01.01.2026, 01:00:00 Uhr“:

TZ=Europe/Berlin date -d @1767225600
# Do 1. Jan 01:00:00 CET 2026

Den Payload lesen Sie auch ohne Tool, indem Sie Base64url in Base64 mit Padding umwandeln:

p=$(printf '%s' "$TOKEN" | cut -d. -f2 | tr '_-' '/+')
while [ $(( ${#p} % 4 )) -ne 0 ]; do p="$p="; done
printf '%s' "$p" | base64 -d; echo

Schritt 3: Zeitstatus und Warnungen auswerten

Direkt unter dem Token zeigt das Tool den Status. Im Test sahen wir „Gültig bis …“, „Abgelaufen seit …“, „Noch nicht gültig“ (wenn nbf in der Zukunft liegt) und „Kein Ablaufdatum (Claim exp fehlt)“. Darunter steht stets der Hinweis: „Der Status bezieht sich nur auf die Zeitangaben. Ob das Token echt ist, zeigt erst die Signaturprüfung.“ Das Tool rechnet ohne Zeittoleranz mit der Uhr Ihres Geräts, viele Bibliotheken erlauben dagegen einige Sekunden Spielraum.

Zusätzlich gibt das Tool Warnungen aus, die im Alltag viel Zeit sparen:

• „Sehr lange Laufzeit“, wenn zwischen Ausstellung und Ablauf Jahre liegen. Für Access Tokens sind Minuten bis wenige Stunden üblich.
• Einen Hinweis, wenn „exp“ sehr groß ist und vermutlich Millisekunden statt Sekunden enthält. Diesen Fehler machen eigene Implementierungen häufig.
• Bei alg: none: Das Token ist nicht signiert, Server dürfen es nie akzeptieren.
• Ein fehlendes exp mit dem Hinweis, dass Tokens immer ablaufen sollten.

Verifizieren: Klicken Sie „Abgelaufenes Token“. Der Status lautet „Abgelaufen“ mit „seit Do., 01.01.2026, 02:00:00 Uhr“. Die Gegenprobe TZ=Europe/Berlin date -d @1767229200 liefert denselben Zeitpunkt.

Schritt 4: Signatur mit Secret prüfen (HS256, HS384, HS512)

Bei den HS-Verfahren berechnen Aussteller und Empfänger einen HMAC über Header.Payload mit demselben Secret. Wer prüfen kann, kann deshalb auch Tokens erzeugen. Tragen Sie das Secret in das Feld „Secret“ ein, das Augensymbol „Secret anzeigen“ macht es sichtbar. Liegt das Secret beim Aussteller Base64-kodiert vor, wie bei manchen Frameworks üblich, aktivieren Sie „Secret ist Base64-kodiert“.

Ergebnis ist „Signatur gültig“ oder „Signatur ungültig“ mit dem Zusatz „Secret passt nicht oder Token wurde verändert“. Das Tool prüft außerdem die Länge: RFC 7518 verlangt ein Secret mindestens so lang wie die Hash-Ausgabe, bei HS256 also 32 Byte. Ein zu kurzes Secret meldet das Tool auch dann, wenn die Signatur stimmt. Ist eine Prüfung mit einem Base64-artigen Secret fehlgeschlagen, schlägt es vor, den Base64-Schalter einzuschalten.

Verifizieren: Ändern Sie im Payload eines gültigen Tokens ein einziges Feld, etwa den Namen, und fügen Sie das Ergebnis ein. Das Tool muss „Signatur ungültig“ melden. In unserem Test mit dem Beispiel-Token war das so, und Python kam zum selben Ergebnis:

python3 - <<'EOF'
import hmac, base64, sys
t = open("token.txt").read().strip(); h, p, s = t.split(".")
mac = hmac.new(b"IHR-SECRET", f"{h}.{p}".encode(), "sha256").digest()
print(base64.urlsafe_b64encode(mac).rstrip(b"=").decode() == s)
EOF

Schritt 5: Signatur mit öffentlichem Schlüssel prüfen (RS, PS, ES, EdDSA)

Asymmetrische Verfahren trennen Signieren und Prüfen. Der Identity Provider signiert mit seinem privaten Schlüssel, Ihre Dienste prüfen mit dem öffentlichen. Sobald ein Token mit RS256 oder ES256 eingefügt ist, wechselt der Bereich „Signatur prüfen“ zu „Öffentlicher Schlüssel“ mit dem Hinweis „PEM, Zertifikat, JWK oder JWK-Set“. Das Tool nennt auch, was es erwartet, etwa „RSA-Schlüssel (mindestens 2048 Bit)“ oder „EC-Schlüssel mit Kurve P-256“.

Der bequemste Weg bei OpenID Connect ist das komplette JWK-Set. Das Tool wählt den passenden Schlüssel über die kid aus dem Header und meldet zum Beispiel „Schlüssel „k1“ aus dem JWK-Set gewählt (2 Schlüssel).“ Private Schlüssel lehnt das Tool laut seiner Hilfe ab. Den öffentlichen Teil erzeugen Sie mit openssl pkey -in key.pem -pubout.

curl -s https://idp.example.com/.well-known/openid-configuration \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["jwks_uri"])'

Verifizieren: Wir haben mit openssl ein RSA-Schlüsselpaar mit 2048 Bit und ein EC-Paar mit P-256 erzeugt, damit Tokens signiert und die öffentlichen Schlüssel als PEM und als JWK-Set eingefügt. Das Tool meldete „Signatur gültig“ mit „RS256 · RSA, 2048 Bit“ bzw. „ES256 · EC, Kurve P-256“. Die Gegenprobe der RSA-Signatur:

openssl dgst -sha256 -verify rsa.pub -signature rs.sig rs.data
# Verified OK

Typische Fehler

„Ein JWT besteht aus drei durch Punkte getrennten Teilen“

Die Meldung nennt die gefundene Anzahl, etwa „Gefunden: 2 Teile.“ Meist wurde das Token beim Kopieren abgeschnitten, oft fehlt die Signatur am Ende einer umgebrochenen Logzeile.

„Payload: Zeichen „!“ ist in Base64url nicht erlaubt.“

Im Token stecken fremde Zeichen, etwa aus einer URL-Kodierung oder Anführungszeichen aus einem JSON-Log. Entfernen Sie alles außer Buchstaben, Ziffern, -, _ und den Punkten.

„Signatur ungültig“, obwohl das Secret stimmt

Prüfen Sie den Schalter „Secret ist Base64-kodiert“, Leerzeichen am Ende des Secrets und ob nach einer Schlüsselrotation ein älterer Schlüssel im Spiel ist. Bei ES-Verfahren muss die Signatur aus R und S mit fester Länge bestehen, eine DER-kodierte Signatur aus openssl ist in einem JWT ungültig.

„Der Schlüssel (EC, Kurve P-256) passt nicht: RS256 braucht einen RSA-Schlüssel.“

Sie haben den falschen Schlüsseltyp eingefügt. Nehmen Sie aus dem JWK-Set den Eintrag mit passender kid oder fügen Sie gleich das ganze Set ein.

Token mit fünf Teilen

Das ist ein verschlüsseltes Token (JWE). Das Tool zeigt den Header, etwa „alg RSA-OAEP, enc A256GCM“, der Inhalt ist nur mit dem Schlüssel des Empfängers lesbar. Eine Signaturprüfung ist hier nicht möglich.

Häufige Fragen

Darf ich Produktivtokens in das Tool einfügen?

Ein noch gültiges Token ist ein Zugangsschlüssel. Auch wenn das Tool lokal rechnet, sollten Sie Produktivtokens und Secrets nur in Werkzeuge einfügen, denen Sie vertrauen, und für Fehlersuche bevorzugt abgelaufene oder Test-Tokens verwenden. Tokens gehören nicht in Tickets oder Chats.

Warum zeigt das Tool „Gültig bis“, obwohl ich die Signatur nicht geprüft habe?

Der Status bezieht sich nur auf die Zeit-Claims. Ein Token mit gültigen Zeiten, aber falscher Signatur ist wertlos.

Kann ich ein abgelaufenes Token verlängern?

Nein. Jede Änderung am Payload macht die Signatur ungültig. Ein neues Token stellt nur der Aussteller aus, bei OAuth 2.0 typischerweise über ein Refresh Token.

Worauf muss mein Server bei der Prüfung achten?

Er sollte den erwarteten Algorithmus fest vorgeben, statt dem alg im Token zu vertrauen. Sonst drohen Tokens mit alg: none oder die Verwechslung von RSA und HMAC, bei der der öffentliche Schlüssel als HMAC-Secret missbraucht wird. Prüfen Sie außerdem immer exp, nbf, iss und aud.

Testumfang

Wir haben den Decoder am 1. Oktober 2026 mit den drei Vorlagen und mit selbst erzeugten Tokens getestet: HS256 mit und ohne „Bearer“, HS512 mit Base64-Secret, RS256 mit PEM und JWK-Set sowie ES256. Signaturen, Zeitstempel und Payloads haben wir mit openssl, Python und date gegengeprüft, alle Ergebnisse stimmten. Manipulierte, abgeschnittene und verschlüsselte Tokens erkannte das Tool mit klaren Meldungen.

Fazit

Der JWT-Decoder ist ein schnelles Diagnosewerkzeug für Anmeldeprobleme: Er zeigt auf einen Blick, ob ein Token abgelaufen ist, für wen es gedacht ist und ob die Signatur zum Schlüssel passt. Besonders hilfreich sind die Hinweise auf Millisekunden-Zeitstempel, zu kurze Secrets und unsignierte Tokens. Die eigentliche Absicherung bleibt Aufgabe Ihrer Server und Bibliotheken, die Algorithmus, Aussteller und Zielgruppe streng prüfen müssen.

Weiterführende Anleitungen und Quellen

• Keycloak auf dem Synology NAS: SSO mit OIDC und SAML
• Single Sign-On: Authentik vs. Authelia mit Traefik Forward-Auth
• Pocket ID mit Docker Compose: Passkey-SSO
• Zitadel mit Docker: Identity Server mit OIDC
• RFC 7519: JSON Web Token
• RFC 7518: JSON Web Algorithms
• RFC 7517: JSON Web Key
• RFC 8725: JWT Best Current Practices