Keycloak Timeout-Wirrwarr? So hängen SSO-, Client- und Token-Laufzeiten wirklich zusammen

„Warum werden meine Nutzer ständig ausgeloggt?“
„Wie lange bleibt ein Token gültig?“
„Und was genau ist eigentlich der Unterschied zwischen einer Session und einem Token?“

Wenn du dich das schon mal gefragt hast, bist du nicht allein – und genau darum geht’s in diesem Beitrag. Wir bringen Ordnung ins Timeout-Chaos von Keycloak und schauen uns an, wie die verschiedenen Laufzeiten zusammenhängen, bevor wir uns im zweiten Teil anschauen, wo und wie man sie in Keycloak einstellen kann.

Teil 1: Verstehen, was abläuft – Sessions und Tokens in Keycloak

Keycloak arbeitet mit mehreren Arten von „Gültigkeitszeiten“ – und jede hat ihre eigene Aufgabe. Wichtig ist, zu verstehen, wie sie zusammenspielen:

SSO-Session – die „Hauptsitzung“

Die SSO-Session (Single Sign-On Session) ist die übergeordnete Session, die Keycloak für einen eingeloggten Benutzer verwaltet – unabhängig davon, welche App (Client) er nutzt.
Solange die SSO-Session lebt, kann sich der Benutzer in anderen Anwendungen automatisch einloggen, ohne sich neu authentifizieren zu müssen.

Client-Session – pro Anwendung (Client)

Jede App, die über Keycloak gesichert ist, bekommt zusätzlich eine eigene Session – die sogenannte Client-Session.
Diese lebt nur, solange der jeweilige Client aktiv mit Keycloak kommuniziert.

💡 Hinweis: Eine SSO-Session kann noch aktiv sein, aber einzelne Client-Sessions können trotzdem abgelaufen sein – und dann muss sich der Nutzer für genau diese App erneut authentifizieren.

Access Token – die Eintrittskarte zu APIs

Das Access Token wird beim Login (oder beim Token Refresh) erstellt und enthält alle wichtigen Infos, z. B. Rollen und Berechtigungen.
Es wird bei jedem API-Aufruf mitgeschickt – und ist in der Regel nur wenige Minuten gültig (z. B. 5 Minuten).

Wenn das Access Token abläuft, braucht man ein neues – aber dafür muss die Session noch gültig sein.

Refresh Token – das Verlängerungs-Tool

Der Refresh Token dient dazu, ein neues Access Token zu holen, ohne dass der Nutzer sich neu einloggen muss.
Er funktioniert aber nur solange die Session (und ggf. die Client-Session) noch lebt.

💡 Hinweis: In neuen Keycloak-Versionen ist die Lebensdauer des Refresh Tokens nicht direkt als separater Parameter sichtbar – sie ergibt sich aus der Session-Gültigkeit.

Zusammenspiel: Ein Beispiel mit API-Zugriff

Stell dir vor:

Du hast eine Webanwendung namens „App A“, die über Keycloak abgesichert ist.
App A greift im Namen des eingeloggten Nutzers regelmäßig auf eine geschützte API zu – z. B. um Benutzerprofile, Daten oder Berechtigungen zu laden.
Diese API erwartet bei jedem Aufruf ein gültiges Access Token.

Laufzeitkonfiguration:

Access Token: 5 Minuten
Client Session Idle: 15 Minuten
SSO Session Idle: 30 Minuten

Ablauf:

Login (Zeitpunkt 0:00):
- Nutzer loggt sich in App A ein → Keycloak erstellt:
  - eine SSO-Session
  - eine Client-Session für App A
  - ein Access Token, das an App A zurückgegeben wird
- App A verwendet dieses Token bei API-Requests im Hintergrund
0:05 – Access Token abgelaufen:
- Die App möchte wieder Daten laden → Access Token ist abgelaufen
- → App nutzt den Refresh Token, um ein neues Access Token bei Keycloak zu holen
- Das klappt, weil die Client-Session und die SSO-Session noch aktiv sind
0:16 – Client-Session abgelaufen (keine Aktivität in App A):
- Nutzer hat die App offen, aber es wurden 15 Minuten lang keine API-Calls mehr gemacht, z. B. weil ein inaktiver Tab offen war
- App versucht jetzt wieder, ein neues Access Token zu holen → Fehlermeldung
- Grund: Client-Session ist abgelaufen → kein Token-Refresh mehr möglich
- → Nutzer muss sich neu bei App A authentifizieren, obwohl die SSO-Session im Hintergrund noch lebt
0:30 – SSO-Session abgelaufen (gesamt):
- Jetzt ist auch die SSO-Session abgelaufen
- Egal welche App – der Nutzer muss sich komplett neu einloggen

Was zeigt das?

Das Access Token ist wie ein zeitlich begrenzter Ausweis, mit dem sich eine App gegenüber APIs ausweist
Wenn es abläuft, kann die App im Hintergrund ein neues holen – aber nur, solange die dazugehörigen Sessions noch gültig sind
Die Kombination aus Token-, Client- und SSO-Timeouts bestimmt, wie lange die App reibungslos funktioniert – und wann der Nutzer erneut aktiv werden muss

Teil 2: Keycloak konfigurieren – wo stelle ich das alles ein?

Jetzt, wo wir wissen, wie Sessions und Tokens zusammenspielen, schauen wir uns an, wo man diese Zeiten in Keycloak einstellt.

Diese Einstellungen findest du auf zwei Ebenen:

Realm-Ebene: globale Defaults

Hier legst du Standardlaufzeiten für alle Clients fest:

Orte:
Realm Settings → Tokens
Realm Settings → Sessions

Einstellung	Bedeutung
SSO Session Idle	Wie lange darf der Nutzer inaktiv sein, bevor er ausgeloggt wird?
SSO Session Max	Wie lange darf die Session maximal dauern, auch bei Aktivität?
SSO Session Idle Remember Me	Inaktivitätszeit mit aktivierter „Remember Me“-Funktion
SSO Session Max Remember Me	Maximale Dauer der Session mit „Remember Me“
Client Session Idle	Wie lange darf eine App (Client) inaktiv sein, bevor die Session abläuft?
Client Session Max	Wie lange darf eine Client-Session maximal bestehen?
Access Token Lifespan	Wie lange ist ein Access Token gültig? (z. B. 5 Minuten)
Refresh Token Lifespan	gibt es in neuen Keycloak-Versionen nicht mehr direkt – sie hängt von der Session-Gültigkeit ab

Client-Ebene: spezifische Overrides

Wenn du für einzelne Anwendungen abweichende Zeitlimits brauchst, kannst du sie direkt im jeweiligen Client setzen:

Ort:
Clients → wähle deinen Client → Settings → Advanced Settings

Dort kannst du z. B.:

Client Session Idle
Client Session Max
Access Token Lifespan (für diesen Client)

… überschreiben.

Exkurs: Warum die Laufzeit des ID-Tokens (fast) egal ist

Das ID-Token wird beim Login ausgegeben und enthält Informationen über den Benutzer – Name, E-Mail, Rollen etc.
Aber: Für die laufende Session ist es nicht entscheidend.

Das ID-Token wird nicht für API-Zugriffe verwendet
Es wird nicht automatisch erneuert
Und: Es kann nicht per Refresh Token erneuert werden
Die laufende Anmeldung funktioniert über:
- die SSO-Session
- die Client-Session
- ggf. Access + Refresh Token

Kurz gesagt: Auch wenn das ID-Token nach ein paar Minuten abläuft – der Nutzer bleibt weiterhin angemeldet.
Das ID-Token wird nicht erneuert, und man muss sich in der Regel nicht aktiv darum kümmern.

Natürlich hat es trotzdem eine Gültigkeitsdauer – und diese richtet sich einfach nach der Laufzeit des Access Tokens.
Keycloak bietet mittlerweile keine eigene Einstellung mehr dafür im Client selbst – was auch zeigt:
Die Lebensdauer des ID-Tokens ist im Normalfall nicht wirklich relevant.

Übrigens, wenn dir der Unterschied zwischen ID-Token und Access-Token noch nicht so klar ist, dann schau doch gerne mal bei diesem Blogpost Access Token vs. ID Token: Was ist der Unterschied? vorbei.

Fazit

Keycloak bietet viele Stellschrauben, um zu steuern, wie lange Nutzer:innen angemeldet bleiben, wann sie erneut authentifiziert werden müssen und wie oft Tokens erneuert werden.

Aber: Viele dieser Einstellungen greifen ineinander – darum lohnt es sich, sie im Zusammenhang zu verstehen, statt nur die „Zahl hochzudrehen“, wenn irgendwas zu früh abläuft.

Wenn du bei der Konfiguration oder bei der Analyse von Session-Timeouts Unterstützung brauchst – melde dich gerne. Wir helfen dir dabei, dein Keycloak-Setup sicher, stabil und verständlich zu gestalten.