JWT-Konfiguration in TypeScript validieren: Algorithmen, Claims & Secrets

Ein JSON Web Token (JWT) ist eine kompakte, URL-sichere Zeichenkette aus drei Base64URL-kodierten Teilen, getrennt durch Punkte: ein Header, der Algorithmus und Tokentyp deklariert, ein Payload mit den Claims und eine Signatur, die beide verbindet. Ein JWT zu validieren bedeutet zu bestätigen, dass alle drei Teile intakt sind und die Claims die Anforderungen Ihrer Anwendung erfüllen — nicht nur, dass die Signatur mathematisch korrekt ist.

Die zwei Schichten der JWT-Validierung

Die kryptografische Validierung bestätigt die Signatur: Der Server prüft, dass das Token mit dem erwarteten Schlüssel signiert und nicht manipuliert wurde. Die Konfigurationsvalidierung geht weiter: Sie prüft, dass das Token von der richtigen Instanz ausgestellt wurde, für genau diesen Dienst bestimmt ist, nicht abgelaufen ist und die erwarteten benutzerdefinierten Claims trägt. Die meisten JWT-Sicherheitslücken entstehen durch unvollständige Konfigurationsvalidierung, nicht durch gebrochene Kryptografie.

• Algorithmus (`alg`) - muss exakt Ihrer Serverkonfiguration entsprechen; nie aus dem Token-Header ableiten
• Ablauf (`exp`) - das Token darf seinen Ablaufzeitpunkt nicht überschritten haben, mit Uhrentoleranz
• Nicht-vor (`nbf`) - das Token darf vor seiner frühesten gültigen Zeit nicht verwendet werden
• Issuer (`iss`) - das Token muss von Ihrem vertrauenswürdigen Auth-Dienst stammen
• Audience (`aud`) - das Token muss für genau diese API oder diesen Dienst bestimmt sein
• Benutzerdefinierte Claims - Rolle, Scope, Tenant-ID oder jedes anwendungsspezifische Feld, von dem Ihre Logik abhängt

Die Algorithmus-Konfiguration ist die sicherheitskritischste Einstellung in der JWT-Verifikation. Wird sie falsch gesetzt, entsteht eine Angriffsklasse, die die Authentifizierung vollständig umgeht. TypeScript-JWT-Bibliotheken geben Ihnen die Werkzeuge, sie korrekt zu erzwingen — aber nur, wenn Sie sie explizit verwenden.

HS256 vs. RS256 — den richtigen Algorithmus wählen

Der Algorithmus-Confusion-Angriff — und wie man ihn verhindert

Algorithmus-Verwirrung entsteht, wenn ein Server das Feld `alg` aus dem JWT-Header liest, um zu entscheiden, wie das Token verifiziert wird, statt den Algorithmus aus der eigenen Konfiguration zu erzwingen. Ein Angreifer ändert den Header von `RS256` auf `HS256` und signiert das Token dann mit dem öffentlichen Schlüssel des Servers als HMAC-Secret. Ein falsch konfigurierter Server akzeptiert es als gültig. Die Korrektur ist eine einzelne Codezeile — aber sie muss vorhanden sein.

// ✗ Vulnerable - algorithm inferred from token header
jwt.verify(token, publicKey);

// ✓ Correct - algorithm enforced from server configuration
jwt.verify(token, publicKey, { algorithms: ['RS256'] });

Validierung der Schlüsselstärke für HS256

Bei HS256 muss das Secret mindestens 256 Bit (32 Bytes) betragen, um der Ausgabegröße von SHA-256 zu entsprechen. Kurze Secrets — weniger als 32 Zeichen, Wörterbuchwörter oder statische Strings wie `"secret"` oder `"development"` — lassen sich mit Werkzeugen wie `hashcat` oder `jwt_tool` trivial per Brute Force knacken. Erzeugen Sie Secrets mit einer kryptografisch sicheren Zufallsquelle: `crypto.randomBytes(32).toString('hex')` in Node.js liefert einen 64 Zeichen langen Hex-String, der die minimale Entropieanforderung erfüllt.

Die JWT-Spezifikation definiert eine Menge standardmäßiger registrierter Claims, die jede Implementierung verstehen sollte. Die Bibliothek `jsonwebtoken` validiert mehrere davon automatisch, wenn Sie die richtigen Optionen übergeben — aber das Schlüsselwort ist „wenn Sie sie übergeben“. Ohne explizite Konfiguration werden die meisten Claim-Prüfungen still übersprungen.

Die Claims exp, nbf und iat

Der exp-Claim (Ablauf) ist ein Unix-Zeitstempel, nach dem das Token nicht mehr gültig ist. Die jsonwebtoken-Bibliothek prüft exp standardmäßig während jwt.verify(). Allerdings kann die Uhrabweichung zwischen Token-Issuer und Verifizierer dazu führen, dass gültige Tokens abgelehnt werden — eine häufige Ursache für „Token abgelaufen“-Fehler in verteilten Systemen, in denen Serveruhren um Sekunden abweichen. Übergeben Sie clockTolerance, um ein kleines Fenster zuzulassen: clockTolerance = 30 akzeptiert Tokens bis 30 Sekunden nach ihrem exp-Wert.

interface JwtPayload {
  sub: string;
  iss: string;
  aud: string;
  exp: number;
  iat: number;
  role: 'admin' | 'user';
}

const payload = jwt.verify(token, publicKey, {
  algorithms: ['RS256'],
  issuer: 'https://auth.example.com',
  audience: 'api.example.com',
  clockTolerance: 30,           // seconds of clock skew to tolerate
}) as JwtPayload;

Die Claims iss und aud

Der `iss`-Claim (Issuer) identifiziert die Herkunft des Tokens. Der `aud`-Claim (Audience) identifiziert den vorgesehenen Empfänger. Beide sind in der JWT-Spezifikation optional, in der Praxis aber kritisch. Ohne `iss`-Validierung kann jeder Dienst, der gültige Tokens mit Ihrem Signaturschlüssel erzeugen kann, sich an Ihrer API authentifizieren. Ohne `aud`-Validierung kann ein Token für Ihre mobile App gegen Ihre Admin-API wiederverwendet werden. Übergeben Sie beide als Optionen an `jwt.verify()`, damit die Bibliothek sie als harte Anforderungen erzwingt statt als informative Felder.

Eine vollständige JWT-Verifikationsfunktion in TypeScript behandelt kryptografische Validierung, Claim-Validierung und Fehlerklassifizierung an einem Ort. So strukturieren Sie sie — mit den vier Schritten, die zum HowTo-Schema passen.

Dies sind die Konfigurationsfehler, die in TypeScript-JWT-Implementierungen am häufigsten auftreten. Jeder davon ist beim Start still und zeigt sich erst als Authentifizierungsfehler oder Sicherheitsvorfall in der Produktion.

`jwt.decode()` statt `jwt.verify()` verwenden

Die Funktion `jwt.decode()` extrahiert das Payload, ohne die Signatur zu prüfen. Sie ist nützlich, um ein bereits vertrauenswürdiges Token zu inspizieren — etwa eine Benutzer-ID aus einem Token zu lesen, das bereits vom Middleware validiert wurde. Sie ist kein Ersatz für `jwt.verify()`. Code, der mit `jwt.decode()` Claims gewinnt und darauf Autorisierungsentscheidungen stützt, akzeptiert unverifizierte Tokens. Das ist eine vollständige Umgehung der Authentifizierung.

Den Fehlertyp in catch-Blöcken ignorieren

Die Bibliothek `jsonwebtoken` wirft drei verschiedene Fehlertypen: `JsonWebTokenError` (fehlerhaftes Token oder ungültige Signatur), `TokenExpiredError` (über den `exp`-Claim hinaus) und `NotBeforeError` (vor dem `nbf`-Claim). Alle Fehler als generisches `Error` zu fangen und in allen Fällen `401 Unauthorized` zurückzugeben, verliert Diagnoseinformationen. Behandeln Sie jeden Typ separat und geben Sie spezifische Meldungen zurück — `Token abgelaufen` gegenüber `ungültiges Token` —, damit Clients und Monitoring-Systeme Konfigurationsprobleme von echten Angriffsversuchen unterscheiden können.

Secrets oder Schlüsselpaare nicht rotieren

Langlebige Signing-Secrets häufen mit der Zeit Risiko an. Ein nie rotiertes Secret bedeutet, dass jedes je damit ausgestellte Token gültig bleibt, falls das Secret kompromittiert wird. Implementieren Sie ein Schlüssel-ID-Feld (`kid`) in Ihrem JWT-Header, damit der Verifizierer den richtigen öffentlichen Schlüssel aus einem JWKS-Endpunkt nachschlagen kann. Dieses Muster erlaubt Schlüsselrotation, ohne Tokens zu invalidieren, die vom vorherigen Schlüssel signiert wurden — jedes Token trägt eine Referenz auf den konkreten Schlüssel, der es signiert hat. Der JWK-Inspector hilft, die JWKS-Endpunkt-Ausgabe zu validieren und privates Schlüsselmaterial zu entdecken, das nicht öffentlich exponiert sein sollte.

Den `none`-Algorithmus akzeptieren

Der `none`-Algorithmus erzeugt ein unsigniertes JWT — jedes Payload mit gültiger Struktur besteht die Verifikation. Frühe JWT-Bibliotheksversionen akzeptierten `none` standardmäßig. Moderne Bibliotheken lehnen es ab, aber nur, wenn Sie die erlaubten Algorithmen in den Verify-Optionen explizit angeben. Fügen Sie immer `algorithms: ['RS256']` (oder Ihren konkreten Algorithmus) hinzu, um die Ablehnung von `none` explizit und resistent gegen Bibliotheksversionsänderungen zu machen.

Einen Test zu schreiben, um einen JWT-Fehler zu reproduzieren, ist oft langsamer, als das Token direkt zu inspizieren. Browserbasierte Werkzeuge lassen Sie Claims, Ablaufzustand und Schlüsselstruktur eines Tokens in Sekunden prüfen — ohne lokale Umgebung, ohne Codeausführung und ohne Übermittlung sensibler Daten an einen Drittanbieter.

Claims dekodieren und inspizieren

Der JWT-Decoder und -Validator dekodiert Header und Payload jedes JWT-Strings und präsentiert alle Claims in einem strukturierten, lesbaren Format. Er prüft auf häufige Sicherheitsprobleme — fehlendes `exp`, schwacher Algorithmus, fehlendes `aud` — und markiert sie mit klaren Diagnosen. Fügen Sie ein Token aus Ihrer Entwicklungs-, Staging- oder Produktionsumgebung ein und bestätigen Sie in zehn Sekunden, ob die Claims dem entsprechen, was Ihr `jwt.verify()`-Aufruf erwartet.

Ablaufprobleme diagnostizieren

Der JWT-Ablauf-Countdown-Rechner liest den `exp`-Claim aus jedem Token und zeigt die exakte verbleibende Lebensdauer oder die Zeit seit Ablauf in UTC und Lokalzeit. Meldet ein Benutzer „Token abgelaufen“, Ihre Logs aber zeigen, dass das Token noch gültig sein sollte, fügen Sie es in den Rechner ein. Der Millisekunden-genue Zeitstempelvergleich zeigt, ob es ein echter Ablauf, eine Uhrenabweichung zwischen Diensten oder ein in Millisekunden statt Sekunden gespeicherter `exp`-Wert ist — ein erstaunlich häufiger Faktor-1000-Bug.

JWKS-Schlüsselmengen inspizieren

Beim Validieren von Tokens eines OIDC-Providers oder eines Dienstes mit JWKS-Endpunkt parst und validiert der JWK-Inspector die Schlüsselmengenstruktur. Er prüft, dass jeder Schlüssel die Pflichtfelder (`kty`, `use`, `alg`, `kid`) hat, validiert Schlüsseltyp und Kurve für EC-Schlüssel und markiert privates Schlüsselmaterial, das nicht öffentlich exponiert sein sollte. Fügen Sie das JSON Ihres JWKS-Endpunkts direkt in das Werkzeug ein oder geben Sie die URL für einen Abruf an.

Eine korrekt konfigurierte JWT-Verifikationsfunktion ist notwendig, aber nicht ausreichend für sichere Authentifizierung. Diese Praktiken vervollständigen das Bild für TypeScript-Produktionsdienste.

Verwenden Sie eine typisierte Payload-Schnittstelle

Definieren Sie eine TypeScript-Schnittstelle für Ihr JWT-Payload und casten Sie das Verifikationsergebnis darauf. Das gibt Ihnen Kompilierzeit-Sicherheit bei Claim-Namen und Wertetypen — ein falsch geschriebener Claim-Name (`userId` vs. `user_id`) wird zu einem TypeScript-Fehler statt zu einem stillen `undefined` zur Laufzeit. Halten Sie die Schnittstelle in einem gemeinsamen Typmodell, damit sie in allen Diensten konsistent ist, die dasselbe Tokenformat verifizieren.

Kurze Token-Lebensdauern mit Refresh-Tokens

Access-Tokens sollten kurze Lebensdauern haben — 15 Minuten bis 1 Stunde für die meisten APIs. Langlebige Access-Tokens (Tage, Wochen) vergrößern das Fenster, in dem ein kompromittiertes Token nutzbar ist. Nutzen Sie einen separaten Refresh-Token-Fluss mit langer Ablaufzeit für die Sitzungspersistenz. Das Refresh-Token rotiert bei jeder Nutzung, und Sperrlisten sind nur für Refresh-Tokens nötig — nicht für Access-Tokens —, solange die Lebensdauern kurz gehalten werden.

Verifikationslogik zentralisieren

Schreiben Sie die JWT-Verifikation an einem Ort — eine Middleware-Funktion oder eine gemeinsame Utility — und verwenden Sie sie überall. Duplizierte Verifikationslogik lädt zu Konfigurationsdrift ein: ein Endpoint prüft `aud`, ein anderer vergisst es, und die Inkonsistenz wird ausgenutzt, bevor jemand es bemerkt. Express-Middleware, NestJS-Guards und Next.js-Route-Handler haben alle saubere Muster, um Auth-Prüfungen zu zentralisieren. Legen Sie Ihre Optionen `algorithms`, `issuer` und `audience` in ein einziges Konfigurationsobjekt, das im gesamten Code importiert wird.

Konfigurieren Sie die Verifikation einmal, erzwingen Sie sie überall. Die einzige JWT-Option, die sich zwischen Endpunkten unterscheiden darf, ist die erwartete Audience.