JWT Claims Erklärt

Was JWT Claims Tun

Ein JWT sind drei base64url-kodierte Segmente, getrennt durch Punkte: header.payload.signature. Der Payload enthält Claims, Schlüssel-Wert-Paare, die Identitäts- und Authorization-Daten tragen. Jeder Claim ist für jeden sichtbar, der das Token hat. Es gibt keine Verschlüsselung, nur eine Signatur, die verifiziert, dass das Token von einer vertrauenswürdigen Partei ausgestellt wurde.

Die Claims fallen in drei Kategorien:

• Registrierte Claims: Durch die JWT-Spezifikation (RFC 7519) definiert. Dazu gehören iss, sub, aud, exp, nbf, iat und jti.
• Öffentliche Claims: Im IANA JSON Web Token Claims Registry registriert oder verwenden einen kollisionsresistenten Namen.
• Private Claims: Vereinbarte Namen zwischen Aussteller und Verbraucher (z.B. role, org_id, permissions).

Die Zeit-Claims: iat, nbf, exp

Diese drei Claims bilden den Lebenszyklus eines Tokens:

iat ──────────── nbf ──────────── Token aktiv ──────────── exp
                  │                                        │
                  └── Token wird gültig                    └── Token läuft ab

iat (Issued At)

Der Unix-Zeitstempel, wann das Token erstellt wurde. Dies ist informativ. Er beeinflusst die Validierung nicht, es sei denn, Ihre Anwendungslogik verwendet ihn, um ein maximales Token-Alter durchzusetzen.

{
  "iat": 1735603200
}

1735603200 = 1. Januar 2025 um 00:00:00 UTC.

nbf (Not Before)

Der Unix-Zeitstempel, wann das Token gültig wird. Wenn ein Token mit einem nbf in der Zukunft ankommt, sollte der Server ihn ablehnen. Dies ist in der Praxis selten. Die meisten Systeme setzen nbf gleich iat.

{
  "nbf": 1735603200
}

exp (Expiration)

Der Unix-Zeitstempel, wann das Token ungültig wird. Dies ist der Schlüssel-Zeitclaim. Der Server muss jedes Token mit exp in der Vergangenheit ablehnen.

{
  "exp": 1735689600,
  "iat": 1735603200
}

Die Differenz beträgt 86400 Sekunden (24 Stunden). Dieses Token hat eine ein-Tages-Lebensdauer.

Standard-Registrierte Claims

Über die Zeit-Claims hinaus definiert die JWT-Spezifikation mehrere Standard-Claims:

iss (Aussteller): Identifiziert, wer das Token erstellt hat. Ihr Auth-Server sollte dies validieren, um zu verhindern, dass Tokens anderer Aussteller akzeptiert werden.

sub (Subjekt): Die Entität, die das Token repräsentiert. Typischerweise eine Benutzer-ID oder ein Service-Kontoname. Verwenden Sie dies in Ihrer Authorization-Logik, um zu identifizieren, wer die Anfrage stellt.

aud (Publikum): Für wen das Token ausgestellt wurde. Wenn Ihr System mehrere Dienste hat (z.B. API-Gateway, Benutzerdienst, Zahlungsdienst), sollte jeder verifizieren, dass der aud-Claim mit seinem eigenen Identifikator übereinstimmt.

jti (JWT-ID): Ein eindeutiger Identifikator für das Token. Verwenden Sie dies für Token-Widerruf. Speichern Sie die jti in einer Sperrliste, wenn der Benutzer sich abmeldet oder das Token widerrufen wird.

Clock Skew: Warum Tokens Zu Früh Abgelehnt werden

Die Uhren der Server sind nie perfekt synchronisiert. Wenn die Uhr des Auth-Servers 30 Sekunden vor der des API-Servers liegt, könnte ein Token mit exp = 1735689600 gegen einen Server validiert werden, der bereits 1735689631 denkt.

Die Lösung ist ein Leeway-Fenster:

// Node.js mit jsonwebtoken
jwt.verify(token, secret, { clockTolerance: 30 }); // 30 Sekunden Toleranz

// Go mit golang-jwt
token, err := jwt.Parse(tokenString, keyFunc,
    jwt.WithLeeway(30 * time.Second),
)

Ein Leeway von 30-60 Sekunden ist Standard. Setzen Sie ihn nicht auf null, oder Sie sehen intermittierende 401-Fehler, die schwer zu debuggen sind.

Häufige Fehler

exp in Sekunden vs. Millisekunden verwenden

Einige Bibliotheken verwenden Sekunden (RFC 7519-Standard), andere Millisekunden. Ein Token mit exp: 1735689600 (Sekunden) sieht wie Jahr 56935 aus, wenn es als Millisekunden interpretiert wird. Überprüfen Sie die Erwartung Ihrer Bibliothek.

exp Zu Weit in Die Zukunft Setzen

Ein Token mit 30 Tagen Lebensdauer bedeutet, dass ein gestohlener Token 30 Tage lang nutzbar ist. Access-Tokens sollten in 15-60 Minuten ablaufen.

Fehlende aud-Validierung

Wenn Ihre API den aud-Claim nicht überprüft, kann ein Token, das für einen anderen Dienst ausgestellt wurde, gegen Ihren Endpunkt verwendet werden. Validieren Sie immer iss und aud.

Sensible Daten in Claims Speichern

Claims sind für jeden mit dem Token lesbar. Keine Passwörter, SSNs oder private Schlüssel in JWT-Claims speichern.

Das Beispiel-Token Dekodieren

Fügen Sie das Beispiel-Token in den JWT Decoder ein, um alle Claims zu dekodieren. Der Payload enthält:

{
  "iss": "https://api.example.com",
  "sub": "user_12345",
  "aud": "https://app.example.com",
  "exp": 1735689600,
  "iat": 1735603200,
  "nbf": 1735603200,
  "role": "admin",
  "permissions": ["read", "write", "delete"]
}

Das Token wurde am Mitternacht UTC am 1. Januar 2025 ausgestellt, läuft 24 Stunden später ab und gewährt user_12345 Admin-Zugriff.