Before diving into Keycloak specifics, let’s fix the plain-English idea in place.

Infinispan is an open-source, distributed, in-memory data grid — essentially a very capable caching system that can spread data across multiple servers, keep copies synchronized, and survive individual servers failing without losing everything. Keycloak embeds Infinispan directly and uses it as the backbone for almost everything that needs to be read constantly and updated frequently during normal operation: active login sessions, realm configuration, user lookups, and more.

Without a technology like Infinispan, every single request Keycloak handles — checking whether a session is still valid, looking up a realm’s settings, verifying a client’s configuration — would need to hit the relational database directly, every time. At any real scale, that would make Keycloak slow and put enormous pressure on the database. Infinispan exists to keep that hot, frequently accessed data close at hand, in memory, right where Keycloak needs it.

The need for Infinispan becomes obvious once Keycloak runs on more than one machine.

A single Keycloak instance could, in principle, just keep its hot data in a plain, local in-memory map. But real production deployments almost always run several Keycloak nodes behind a load balancer, both for capacity and for resilience against any one node failing. That introduces a hard problem: a user might log in through node A, then have their very next request land on node B. If node B has no idea that user’s session exists, the whole system breaks.

Infinispan solves exactly this. Rather than each node keeping an isolated, local cache, Infinispan lets Keycloak nodes form a cluster and share cache data — so a session created on node A is visible, quickly, to node B as well. This is what makes a load-balanced, multi-node Keycloak deployment behave, from the outside, like one single, consistent system.

Keycloak actually leans on all three of these, each for a different purpose.

Keycloak’s general pattern is to treat the database as the ultimate source of truth for anything that must survive a restart, while using Infinispan as the fast, shared layer for data that’s read constantly but doesn’t necessarily need permanent storage — with a notable, deliberate exception discussed shortly.

Keycloak doesn’t use just one big cache — it defines several, each dedicated to a specific kind of data.

Splitting responsibilities this way lets Keycloak tune each cache’s behavior — how it replicates, how long entries live — independently, based on how that particular kind of data is actually used.

Not every Infinispan cache in Keycloak behaves the same way — some are local, some are truly distributed.

Some caches, like the ones holding realm and user configuration, are primarily local to each node for maximum read speed, but Keycloak uses Infinispan’s clustering to invalidate those local caches across every node whenever the underlying data changes — so a configuration update made on one node quickly clears the stale, cached copy everywhere else. Other caches, particularly the session-related ones, are genuinely distributed, meaning the actual data itself, not just an invalidation signal, is shared and replicated across nodes.

flowchart TD
    subgraph Node A
        LA["Local Cache Copy"]
    end
    subgraph Node B
        LB["Local Cache Copy"]
    end
    Admin["Admin updates a realm setting on Node A"] --> LA
    LA -->|Invalidation message via Infinispan| LB
    LB --> Fresh["Node B fetches fresh data
from the database on next read"]
        

Keycloak can run Infinispan in more than one topology, depending on deployment needs.

Clustering only works if nodes can actually discover one another — that’s handled by a companion technology called JGroups.

Underneath Infinispan’s clustering sits JGroups, a toolkit for reliable group communication between servers. JGroups is responsible for the mechanics of forming a cluster: nodes discovering each other (through various discovery mechanisms depending on the environment, such as Kubernetes-aware discovery or a shared database ping table), joining the group, and reliably exchanging messages once connected.

Tracing a concrete example makes the whole picture click into place.

sequenceDiagram
    participant U as User
    participant LB as Load Balancer
    participant N1 as Keycloak Node 1
    participant N2 as Keycloak Node 2
    participant IC as Infinispan Session Cache

    U->>LB: Login request
    LB->>N1: Routed to Node 1
    N1->>IC: Write new session
    IC->>IC: Replicate across cluster
    N1-->>U: Login successful

    U->>LB: Next request
    LB->>N2: Routed to Node 2 this time
    N2->>IC: Look up session
    IC-->>N2: Session found (replicated from Node 1)
    N2-->>U: Request served normally
        

Not everything Infinispan touches lives only in memory — offline sessions are the clearest example of the exception.

Regular user and client sessions live primarily within Infinispan’s in-memory cache, which is fast but, by itself, doesn’t guarantee the data survives a full cluster restart. Offline sessions, by contrast, are deliberately written straight into the relational database from the moment they’re created, precisely because they’re meant to survive far beyond typical session lifetimes — including through restarts, upgrades, and node failures.

For organizations running Keycloak across multiple physical sites, Infinispan’s reach can extend even further.

Larger deployments sometimes run Keycloak across two or more geographically separate datacenters for resilience or performance reasons. Infinispan supports cross-datacenter replication modes that let session and cache data be synchronized not just across nodes within one site, but across entire sites — so a user’s session created in one datacenter can, depending on configuration, remain usable if traffic is routed to another.

Because Infinispan sits on the critical path of nearly every Keycloak request, its configuration has a real, measurable effect on performance.

Because Infinispan carries session and identity-related data across the network between nodes, it deserves its own security attention.

Infinispan solves a real scaling problem, but it does add its own layer of operational complexity.

A few recurring habits distinguish healthy Keycloak clusters from troubled ones.

A short, practical checklist for teams running Keycloak across more than one node.

Infinispan’s role becomes visible wherever Keycloak needs to scale beyond a single server.

Because Infinispan underlies so much of Keycloak’s behavior, keeping an eye on it is essential operational practice.

In its default, embedded mode, no — it’s bundled directly inside Keycloak. A separate, external Infinispan or Data Grid deployment is only needed for more advanced topologies.

Not necessarily. Configuration data can be reloaded from the database, and offline sessions specifically are persisted there as well. Regular, in-memory-only session data, however, would need users to log in again.

No. JGroups handles the underlying cluster communication and node discovery, while Infinispan builds its distributed caching functionality on top of that communication layer.

Yes. Even a single node uses Infinispan’s local caching capabilities, just without the clustering and replication behavior that only becomes relevant once multiple nodes are involved.

Infinispan is deeply integrated into Keycloak’s architecture as its caching and clustering layer, so it isn’t treated as a casually swappable component in typical deployments.

For data that’s read far more often than it changes, like realm configuration, it’s often more efficient to keep a fast local copy per node and simply signal “this is now stale” across the cluster, rather than constantly pushing the full data everywhere.

Infinispan is the distributed, in-memory data grid Keycloak embeds to keep frequently accessed data — sessions, realm configuration, user records — fast to read and consistent across a cluster of servers. Working alongside JGroups for cluster communication, and complemented by the database for anything that genuinely needs to survive restarts, Infinispan is what allows a load-balanced group of Keycloak nodes to behave, from a user’s point of view, like one single, coherent system. Getting the most out of it means treating cluster networking, memory sizing, and cache health as real, ongoing operational concerns — not a detail that takes care of itself once the servers are running.