In Keycloak, “caches” are used for different things:

• They cache information that is already stored in the database (like realm or user information),
• You can choose to store data in caches or in the database (for example for user sessions)
• Some data is exclusively stored in memory (for example login failure data)
• They help coordinating a Keycloak cluster and invalidating cached data (the work cache)

This is quite a mix of functionality. While it was sometimes difficult to set things up with older versions, the most recent versions should be a lot more simple to set up and upgrade.

This post summarizes what we have done in the past, what we think the current state is, and where we want to head in the future. Please comment on this discussion to provide ideas and also context in which setups this works well or where it needs improvements.

How we made them simpler to use

We evolved the area of caching in the past based on user feedback:

• People struggled with high memory usage -> we’re rewritten the session handling to use the database instead for regular sessions. The same mechanism is now also used for offline sessions when persistent sessions are disabled.
• They wanted persistent sessions to scale -> @pruivo showed for the 26.4 release that it scaled quite linear with your DB CPUs in https://www.keycloak.org/2025/10/keycloak-benchmark
• People struggled with setting up ISPN clustering -> we’ve introduced JDBC_PING and deprecated all other options. A show-of-hands during a talk at Keycloak DevDay showed that 12 months after we introduced it, 95%+ of the room was using it.
• People struggled with configuring the caching XML file -> the file is now empty, shouldn’t be touched by users, and instead all supported options are available as documented CLI options for Keycloak.
• One customer pointed out that login failure caches were growing and giving problems on rolling restarted. We’ve sat down together and improved this in 26.5: The login failure caches should now be significantly smaller for some variants, and rolling restarts should be smoother. Infinispan: LoginFailures entries should expire #44801

Working for the vast majority of users?

To gather some information from the Keycloak repository: We have not seen many open issue around Infinispan lately

• with most items around maturing the JDBC_PING implementation mentioned above.

We plan to continue to improve it, but it would require some specific information about a user’s setups, performance analysis, etc. We would appreciate it if people would engage in GitHub issues to provide context and data about the problems they are experiencing. We’ll be happy to dive into details with you.

How caching should evolve

What currently is the field of “caching” in Keycloak, is actually a mix of different functionalities. It can be split-up and changed depending on different architecture decisions on the overall Keycloak project.

Here’s some of the ongoing work and alternatives that already exist:

• There are currently different modes of deployment: sessions in the database plus caching (default), sessions in memory (when “persistent sessions” is disabled). In the multi-cluster aka multi-site, there is the option to use an external Infinispan where user sessions are kept in the database only (not cached), and all remaining distributed caches are placed in an external cache, but with user sessions stored in the database. Technically it can also be used with a single cluster.
  There is also the experimental feature “clusterless” which allows storing the user sessions only in the external Infinispan and not in the database.
• If you are using persistent sessions, you can disable caching of the sessions using an spi-option, which would remove the 4 user session caches from the embedded distributed Infinispan via “spi-user-sessions--infinispan--use-caches”. We didn’t disable it by default as we’re lacking data on how disabling caches would be beneficial to users.
• There is an idea of a multi-cluster / multi-region setup with active/passive and “warm” standby. Support waiting for a writable database in warm standby failover setups #46991
• By the end of the year, we plan to have a whitepaper guiding which of the setups serves which kind of needs / shows what kind of behavior. This would then also set out the strategy if we would want to support “clusterless” (user sessions stored in an external Infinispan), and how we want to proceed with the warm-standby multi-cluster / multi-region setup.

Looking further into the future:

• The brute-force-detection cache is one of the bigger caches. At the same time it is information that probably should not be stored in memory, but persisted in the database to survive restarts or clearing of caches. In KC 26.5, we reduced its memory size (see Infinispan: LoginFailures entries should expire #44801). In the future, this might be completely rewritten to allow for better adaptive authentication, and different information to be stored.
• The work cache is mainly used to invalidate data cached in the local caches. As it is done synchronously, it also requires a synchronously replicated database. There could be different ways of invalidating the local caches, for example by following the WAL of the database to then invalidate the entries in the caches. This would allow for very different setups that would also scale better.
• Any multi-region setup is IMHO limited by the latency between the regions. Any synchronous replication between regions would slow down Keycloak. Solving this would need to start on the protocol level / in the service layer of Keycloak, and should not be solved potentially with conflict resolution patterns on the storage level (be it some kind of cache or the database). We’re open to discuss with anyone who wants to dedicate engineering quality time to come up with solutions to multi-region setups on the protocol / service layer.

Changing things one step at a time

So where should we start to change things? Post your comment below to engage in this conversation!