M2M-Authentifizierung

Private-Key-JWT, kurzlebige Access Tokens und die lokale Autoritätsprüfung bei jedem Request.

11 Min. Lesezeit

Vertrauensmodell

Ein Token übernimmt den Mandanten nicht aus einem Request-Parameter. Die verifizierte ZITADEL-Subject-ID wird lokal auf eine aktive Installation aufgelöst; erst diese Bindung bestimmt die Organisation.

Anwendung, Installation, Organisation, Feature-Flag und angeforderter Scope werden bei jedem Request erneut geprüft. Pause, Widerruf und Scope-Reduktion wirken deshalb sofort.

Private-Key-JWT Assertion

Claim	Wert
iss / sub	oauth_subject der Installation
aud	gelieferter ZITADEL Issuer
iat / exp	kurze Laufzeit, höchstens wenige Minuten
jti	kryptografisch eindeutige Assertion-ID
kid (Header)	credential_key_id der Installation
alg	RS256

Payloadjson

{
  "iss": "<oauth_subject>",
  "sub": "<oauth_subject>",
  "aud": "<oauth_issuer>",
  "iat": 1915898400,
  "exp": 1915898700,
  "jti": "018f-unique-assertion-id"
}

JWT-Bearer-Grant

Sende die Assertion an den gelieferten Token-Endpunkt. Der oauth_audience_scope sorgt dafür, dass das Access Token für die Club API ausgestellt wird. Cache es nur bis kurz vor expires_in.

Form Bodytext

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
scope=openid <oauth_audience_scope>
assertion=<signed-rs256-jwt>

Was die API prüft

RS256-Signatur und aktuelles JWKS
Issuer und Audience
iat, nbf, exp, jti und maximale Token-Laufzeit
Subject-Bindung zur Installation
aktive Anwendung, Organisation und Installation
lokal aktuell gewährte Scopes

Rotation und Widerruf

Ein Club Owner kann das Credential rotieren, eine Installation pausieren oder dauerhaft widerrufen. Nach Rotation ist nur der neue Key gültig. Integrationen müssen Credential- und Tokenfehler als Betriebszustand sichtbar machen und dürfen nicht auf statische Token ausweichen.