JWT Claims erklärt: So lese ich iss, aud, exp und sub

Wenn ich ein JWT dekodiere, lese ich die Claims nicht einfach von oben nach unten. Ich nutze eine feste Reihenfolge, weil ich damit schneller beantworten kann: Wer hat dieses Token ausgestellt? Für wen ist es bestimmt? Ist es zeitlich gültig? Wen oder was repräsentiert es? Welche Berechtigungsdaten sind enthalten?

Für die erste Sichtung nutze ich den JWT Decoder. Danach gehe ich von standardisierten Claims zu provider- und anwendungsspezifischen Claims weiter.

Meine Reihenfolge beim Lesen eines Payloads

Bei einem Payload wie:

{
  "iss": "https://auth.example.com/",
  "sub": "user_123",
  "aud": "api://orders",
  "scope": "orders:read orders:write",
  "iat": 1789200000,
  "exp": 1789203600
}

prüfe ich normalerweise zuerst:

1. iss — welcher Issuer behauptet, das Token ausgestellt zu haben?
2. aud — für welche API oder welchen Empfänger ist es bestimmt?
3. exp und nbf — liegt das Token im erlaubten Zeitfenster?
4. iat — wann wurde es laut Payload ausgestellt?
5. sub — welches Subject repräsentiert es?
6. scope, roles, groups — welche Authorization-Daten sind vorhanden?
7. jti, azp, auth_time, acr, amr — welcher zusätzliche Protokollkontext ist relevant?

Diese Reihenfolge verhindert, dass ich mich von einem großen Payload ablenken lasse.

iss: Wer hat das Token ausgestellt?

iss steht für Issuer.

{ "iss": "https://login.example.com/" }

Ich vergleiche diesen Wert mit dem Issuer, den meine API tatsächlich vertraut. Ein vertraut aussehender URL-String reicht mir nicht.

Vor der Signaturprüfung ist auch iss nur untrusted input. RFC 8725 macht außerdem klar, dass die für die kryptografische Prüfung verwendeten Keys zu dem Issuer gehören müssen, dem die Anwendung vertraut.

Bei Problemen nutze ich den JWT Debugger und die Anleitung zur Issuer Validation.

aud: Für wen ist das Token gedacht?

aud kann ein String sein:

{ "aud": "api://orders" }

oder eine Liste:

{ "aud": ["api://orders", "api://reporting"] }

Wenn die Orders API api://orders erwartet, das Token aber api://billing enthält, kann die Signatur trotzdem korrekt sein. Das Token ist dann einfach für einen anderen Empfänger bestimmt.

Diesen Fall behandle ich in der Audience-Mismatch-Anleitung.

exp: Wann endet die Akzeptanzzeit?

exp ist eine NumericDate in Sekunden seit Unix Epoch. Bei JavaScript denke ich deshalb immer an den Unterschied zu Millisekunden.

Für eine lesbare Darstellung nutze ich den JWT Expiry Checker. Ein exp in der Zukunft beweist aber nicht, dass das Token insgesamt gültig ist. Es bedeutet nur, dass diese eine Zeitbedingung noch nicht verletzt wurde.

Die Details zu Units, Clock Skew und Missing Expiration stehen in der JWT-exp-Anleitung.

nbf: Ab wann darf das Token verwendet werden?

nbf bedeutet Not Before. Ein Token kann noch lange vor exp liegen und trotzdem abgelehnt werden, wenn nbf in der Zukunft liegt.

Bei Fehlern direkt an der Zeitgrenze prüfe ich die Uhren von Issuer und Verifier sowie eine eventuell konfigurierte kleine Clock Tolerance.

iat: Wann wurde es ausgestellt?

iat ist für mich Kontext, nicht automatisch eine Acceptance Rule.

Ich nutze es, um zu fragen:

• Passt das Token zur Login-Session, die ich gerade untersuche?
• Ist es unerwartet alt?
• Ist die Differenz zwischen iat und exp plausibel?
• Liegt iat auffällig in der Zukunft?

Eine maximale Token Age muss die Anwendung selbst definieren.

sub: Wer oder was ist das Subject?

sub kann einen Benutzer, einen Service oder einen anderen Principal identifizieren.

Ich interpretiere sub nie ohne Issuer-Kontext. Identische sub-Werte von zwei verschiedenen Issuern müssen nicht dieselbe Identität meinen. In vielen Systemen ist die Kombination iss + sub aussagekräftiger.

jti: Token-ID, aber keine automatische Revocation

jti kann ein einzelnes JWT eindeutig kennzeichnen. Seine bloße Existenz erzeugt jedoch weder Replay Protection noch Revocation.

Dafür braucht es zusätzliche Policy und häufig serverseitigen Zustand.

scope, roles und groups

Diese Claims sind beim Debugging wichtig, haben aber keine universelle Bedeutung.

{
  "scope": "profile orders:read",
  "roles": ["support", "billing"],
  "groups": ["employees"]
}

Ein Provider nutzt einen space-separated Scope-String, ein anderer namespaced Claims oder eigene Rollenstrukturen. Deshalb behandle ich einen Claim namens roles nicht automatisch als autoritativ.

Wenn Authentication funktioniert, aber eine Operation mit 403 endet, prüfe ich diese Schicht als Nächstes.

Zusätzliche OAuth- und OIDC-Claims

Je nach Token-Typ schaue ich auch auf:

• azp — Authorized Party;
• auth_time — Zeitpunkt der Benutzer-Authentifizierung;
• acr — Authentication Context Class Reference;
• amr — Authentication Methods References.

Ich verwende sie nur dann für Entscheidungen, wenn das konkrete Protokoll oder der Provider ihre Semantik definiert.

Meine wichtigste Trust-Regel

Ich trenne drei Fragen:

1. Decode: Was behauptet der Payload?
2. Verify: Ist die Signatur mit vertrauenswürdigem Key Material korrekt?
3. Validate: Passen Issuer, Audience, Zeit, Token-Typ und Permissions zur aktuellen Anwendung?

Ich springe nicht von Schritt 1 direkt zu „Benutzer ist authentifiziert“.

Meine praktische Claim-Checkliste

1. JWT im Decoder lesen, aber noch nicht vertrauen.
2. iss mit dem konfigurierten Issuer vergleichen.
3. aud mit der aktuellen API vergleichen.
4. exp, nbf, iat als gemeinsame Timeline lesen.
5. sub immer im Issuer-Kontext interpretieren.
6. Scopes/Roles/Groups erst nach erfolgreicher Authentication bewerten.
7. Signatur mit einem Key prüfen, dessen Quelle an den Trusted Issuer gebunden ist.
8. Provider-spezifische Claims mit offizieller Provider-Dokumentation vergleichen.

So fokussiere ich zuerst die Claims, die Trust, Recipient, Zeit und Authorization erklären, statt jeden Payload-Key gleich zu behandeln.