Keycloak high availability

Losing a Keycloak node does not automatically mean every signed-in user keeps their session. Whether users continue without interruption or must sign in again depends on where user sessions and login state are held in your chosen architecture, and that is a design decision to make before go-live. Keycloak clusters share session and login state across nodes through Infinispan caches, but how far that state is replicated, and what a surviving node can recover, depends on the architecture and version. Plan for the case where some users are asked to authenticate again, and treat transparent continuation as something to prove in testing rather than assume.

The three documented high availability designs handle session state differently, so the choice matters for this question. In a single cluster spread across availability zones, sessions are held in the cluster's distributed caches, and the surviving nodes depend on cache ownership settings to find them. The multi-cluster v2 design does not use an external Infinispan cluster, so confirm how session state moves between sites. The deprecated multi-cluster v1 design used a separate Infinispan cluster per site, which means a site-level failure affects a different set of state. The Keycloak 26.8 upgrade notes recommend moving from the deprecated multi-site feature to the stateless feature, so confirm what that change means for sessions before you commit to a design. In every case, both supported designs still require a synchronously replicated database, and you should confirm with the high availability overview which session data lives in the database and which lives in caches.

Users will experience a node loss in one of several ways, and each depends on a different setting. A user who is midway through a sign-in can lose that attempt and must start again. A user with an existing Keycloak single sign-on session may continue silently if the session survives the failure. Access tokens remain valid until they expire, so the application may keep working briefly, but a token refresh that fails forces a new sign-in. The SSO session idle and maximum lifetimes, along with token lifetimes, decide how long these states last. Write these expectations down per realm and per client, and confirm the values with the security team, since shorter lifetimes change both user experience and risk.

The load balancer shapes how often users are affected. Sticky sessions send a user back to the same node, which keeps cache lookups local during normal operation but means that user is directly affected when that node fails. Without stickiness, requests spread across nodes and a surviving node must find the state it needs, which is the case your cache design must support. Set balancer idle timeouts so they do not close long-lived connections before Keycloak does, and configure health checks that remove a failed node quickly. Agree with the application teams how their clients handle an expired session, a 401 response or a redirect back to sign-in, and confirm that no redirect loop appears after a failover.

Test the behavior instead of relying on the documentation alone. In a staging environment that mirrors production, stop one node while a test user is in each state: during sign-in, with an idle SSO session, during a token refresh and during a consent step. Record for each flow whether the user continued, was asked to sign in again or saw an error, and how long recovery took. Repeat the test after each Keycloak upgrade, because session behavior can change between versions. Compare the results with your availability target and with what the application teams can tolerate. Document the result as the expected behavior for users, and do not describe it to stakeholders as zero impact.

A high availability design is only proven when it is tested against targets the business has agreed in writing. Before any test runs, record the sign-in availability target, the acceptable recovery time after each failure type, and the sessions users may lose during an incident. These are business decisions, so confirm them with application owners and the risk function, not only with the platform team. Without written targets, the test result has nothing to be measured against, and the team ends up debating after the fact whether an interruption was acceptable.

The plan should cover five cases. First, node loss: stop one Keycloak node under steady sign-in load. Second, zone loss: if the design spans availability zones, take down every node in one zone. Third, database primary failover: trigger a failover on the synchronously replicated database and confirm that Keycloak reconnects without a manual restart. Fourth, load balancer health check failure: make one node fail its health check and confirm that traffic drains from it cleanly. Fifth, a rolling restart during a minor upgrade, one node at a time, with the new version. For each case, write the fault injection method, the expected behavior, the rollback step and the owner who runs it.

For each run, capture three kinds of evidence. The first is login success rate, taken from the load generator and cross-checked against login failure counters on the Prometheus-format /metrics endpoint, which is served on the management interface only when metrics are enabled. The second is time to recover, measured from fault injection until the success rate returns to baseline, using request latency histograms and cache health signals where your configuration exposes them. The third is session survival: seed test users with active sessions and refresh tokens before each fault, then record which users must sign in again. In Keycloak 26.8, login failures are persisted to the database by default, so confirm the extra write load during the test window.

The failure-safe check is a separate test and it must pass. When the database or the cluster is unavailable, Keycloak must not allow any sign-in to succeed by skipping checks. Make the database unreachable, then attempt sign-ins with valid credentials, wrong passwords, disabled users, expired accounts and flows that require a second factor. Every attempt should fail closed, with no tokens issued and no session created. Confirm that the load balancer does not route traffic to a node that cannot reach the database. Keep the output of this check as evidence, because an auditor or a security reviewer will ask for it.

Run these tests in a production-like environment with the same Keycloak version, the same database engine and replication topology, the same reverse proxy, TLS settings and load balancer, and a comparable node count. Results from a smaller lab rarely transfer to production. Repeat the full set after every Keycloak upgrade, including minor releases, and after any change to the database, network path or load balancer configuration. When you request a quote, ask for the test cases, the success criteria tied to your agreed targets, and a written report of results and open findings as deliverables.