Skip to Content

Tokens

Wofür ID, Access und Refresh Token jeweils da sind, wer welchen validiert, wie lange sie leben und wie Rotation und sichere Ablage funktionieren.

Eine einzige Anmeldung kann drei verschiedene Token erzeugen, und die meisten Integrationsprobleme entstehen daraus, dass verwechselt wird, wofür welcher da ist. Diese Seite ist die Nachschlagetabelle: Zweck, Audience, Lebensdauer und Umgangsregeln pro Token-Typ.

Die drei Token

TokenAdressiert anWofür er da istValidiert von
ID TokenDie Anwendung (ihre Client ID ist die Audience)Belegt, wer sich angemeldet hat, und trägt Profil-Claims (sub, name, email, ...).Der Anwendung, üblicherweise über ihre OIDC-Bibliothek.
Access TokenEine API (ihre Kennung ist die Audience)Autorisiert Aufrufe dieser API und trägt die gewährten Scopes.Der API, bei jeder Anfrage; siehe Eine API schützen.
Refresh TokenDie Plattform selbstLässt die Anwendung ihr Access-Token später erneuern, ohne den Benutzer zurück auf die Anmeldeseite zu schicken.Der Plattform, am Token-Endpunkt.

Der häufigste Fehler ist, den ID Token an eine API zu schicken. Ein ID Token authentifiziert den Benutzer gegenüber der Anwendung, und seine Audience ist die Client ID der Anwendung, sodass eine korrekt implementierte API ihn ablehnt. Schicken Sie den Access Token an APIs, und behandeln Sie ihn im Client als opak: Sein Inhalt ist ein Vertrag zwischen Plattform und API, nicht mit der Anwendung.

Access-Token-Formate

  • Für eine registrierte API (der Client hat die Kennung der API als Resource Indicator übergeben): ein signiertes JWT mit der Kennung der API als aud, den gewährten Scopes in scope und dem Aufrufer in sub. Die API validiert es offline gegen die veröffentlichten Schlüssel der Plattform. Mit aktiviertem RBAC trägt es zusätzlich permissions-/roles-Claims.
  • Ohne Ziel-API: ein opaker Token, der nur am UserInfo-Endpunkt der Plattform verwendbar ist. Opake Token (und Refresh Token) können am Standard-Token-Introspection-Endpunkt geprüft und am Revocation-Endpunkt widerrufen werden; beide sind im Discovery-Dokument aufgeführt. Ein Client darf seine eigenen Token prüfen; Token anderer Clients nur eine in der Admin-Konsole angelegte Anwendung mit Client-Secret oder Schlüssel (ein Resource Server), keine dynamisch registrierte.

Lebensdauern

Token / ArtefaktLebensdauerWo konfiguriert
Authorization Code1 Minute, einmalige VerwendungFest
Access Token für eine APIStandard 1 Tag (2 Stunden über Implicit-Flows)Pro API, auf ihrer Einstellungs-Registerkarte; siehe APIs
Access Token ohne Ziel-API (UserInfo)1 StundeFest
Machine-to-Machine-Token ohne Ziel-API10 MinutenFest
ID TokenStandard 1 StundePro Anwendung; siehe Anwendungen
Refresh Token14 Tage, durch Rotation auf insgesamt bis zu 1 Jahr verlängerbarFest; siehe unten
Device Code10 MinutenFest
Single-Sign-on-SessionInaktivitäts- und absolute TimeoutsInstanzweit unter Settings → Login, pro Directory übersteuerbar; siehe Login-Einstellungen

Refresh Token

Wann einer ausgestellt wird. Die Anwendung muss den Grant-Typ refresh token aktiviert haben. First-Party-Anwendungen (ohne Consent-Bildschirm) erhalten dann automatisch einen; Anwendungen mit aktiviertem Require user consent erhalten nur dann einen, wenn der Benutzer den Scope offline_access gewährt hat.

Rotation. Refresh Token rotieren, statt ewig zu leben:

  • Ein Public Client (Single-Page- oder Native-App, kein Client Secret) erhält bei jeder Verwendung einen Ersatz-Refresh-Token. Bei browserbasierten Clients behält der Ersatz die Restlaufzeit, Rotation verlängert sie also nicht.
  • Ein Confidential Client behält seinen Refresh Token, bis etwa 70% seiner Lebensdauer verstrichen sind; die nächste Verwendung stellt dann einen frischen 14-Tage-Token aus.
  • Unabhängig von der Rotation endet eine Refresh-Token-Kette spätestens ein Jahr nach der ursprünglichen Anmeldung; danach muss sich der Benutzer erneut anmelden.

Ein wegrotierter (verwendeter) Refresh Token ist ungültig; wenn Ihr Client Token persistiert, speichern Sie immer den neuesten aus jeder Antwort.

Widerrufen. Eine Anwendung kann einen Refresh Token proaktiv am Revocation-Endpunkt (im Discovery-Dokument aufgeführt) widerrufen, was beim eigenen Logout gute Praxis ist. Benutzer können ihre Sessions über ihr Konto-Portal beenden ("überall abmelden"), und sessiongebundene Token enden mit ihnen; siehe den nächsten Abschnitt.

Token und Abmeldung

Die Abmeldung beendet die SSO-Session der Plattform, Token folgen aber ihren eigenen Regeln:

  • Token, die ohne offline_access ausgestellt wurden, sind an die Session gebunden. Opake Token funktionieren ab dem Ende der Session nicht mehr.
  • Ein JWT Access Token kann nicht zurückgerufen werden: APIs validieren ihn offline, sodass er auch nach der Abmeldung bis zu seinem Ablauf technisch verwendbar bleibt. Wenn dieses Zeitfenster für eine API relevant ist, verkürzen Sie deren Access-Token-Lebensdauer, statt sich auf den Logout zu verlassen.
  • Mit offline_access bezogene Refresh Token überleben die Abmeldung absichtlich (genau das bedeutet Offline-Zugriff). Sie enden, wenn sie ablaufen, die Ein-Jahres-Grenze erreichen oder widerrufen werden.
  • Anwendungen können über Back-Channel-Logout über die Abmeldung informiert werden; siehe Token-Lebensdauern und Logout. Wie Plattform-Session, Anwendungs-Sessions und die Session eines vorgelagerten Identity Providers zusammenhängen, beschreibt User lifecycle: Sessions.

Token speichern

  • Gegen Skripte in der Seite (Cross-Site-Scripting): Ein Token in localStorage oder sessionStorage ist für jedes eingeschleuste Skript lesbar. Browser-Apps halten Token nur im Speicher und überbrücken die kurze Access-Token-Lebensdauer mit der Refresh-Token-Rotation.
  • Gegen andere Software auf dem Gerät: Ein Token in einer einfachen Datei oder einem Einstellungsspeicher ist einen Dateizugriff entfernt. Native Apps verwenden den geschützten Speicher des Betriebssystems (Keychain, Keystore, Credential Locker).
  • Gegen den Browser als Ganzes: Eine serverseitige Anwendung braucht den Browser nie als Token-Speicher. Halten Sie Token auf dem Server, gebunden an Ihr eigenes Session-Cookie.
  • Gegen Lecks bei der Übertragung und in Logs: Senden Sie Token nur über TLS im Authorization-Header, nie in URLs (sie landen in Proxy- und Server-Logs), und schreiben Sie sie nie selbst in Logs.

Verwandte Themen

Auf dieser Seite