Introducing Locke: a Keycloak Distribution That Lets You Choose Your Cache

“The liberty of man, in society, is to be under no other legislative power but that established, by consent, in the commonwealth.”

John Locke, Second Treatise of Government, §95

Keycloak is excellent software. This post is not a complaint about it. It is an explanation of one design choice we wanted to make differently, why we built a distribution to make it possible, and what the numbers look like when you do.

Today we are releasing Locke: an Apache 2.0 distribution of Keycloak that ships with both the upstream embedded Infinispan cache and a Redis cache backend. The operator chooses at boot with a single environment variable. Choose Infinispan and Locke is the Keycloak it was built from, unchanged. Choose Redis and Keycloak’s caching comes off the embedded JGroups cluster: the shared session-class caches (authentication sessions, login failures, single-use tokens) move to a managed Redis, while the local realm, user, and authorization caches keep their fast in-JVM copy and coordinate invalidation over Redis pub/sub instead of JGroups. Either way there is no JGroups cluster to operate.

The one choice Keycloak does not give you

Keycloak lets you choose your database from a long list. It does not let you choose your cache.

The stated reason for keeping the cache fixed is to avoid adding operational dependencies, and that principle is reasonable. The wrinkle is that Keycloak already supports, and for high availability effectively requires, an external Infinispan deployment, which is itself a distributed system an operator has to stand up, tune, and keep alive. So the “no extra dependency to operate” goal and the realities of running Keycloak at scale already sit in tension.

That tension is the whole idea behind Locke: if an operator is going to run an external clustered cache anyway, they should be allowed to pick one their cloud already manages for them.

This is not a need we invented

The request has a long paper trail.

• keycloak/keycloak#24849 asked for a Redis cache option and collected 36 thumbs-up reactions before it was closed on 2026-04-29 with this comment from the project lead:

  “We do not plan to add support for Redis to Keycloak. For a more detailed response, please see https://github.com/keycloak/keycloak/discussions/48577”

  @stianst, 2026-04-29

• keycloak/keycloak#13983 is a discussion open since 2022-08-25 asking for the same thing.

• Operational pain running embedded and external Infinispan on Kubernetes shows up repeatedly: #48947 (out of memory), #33658, and #46491.

Running highly available Infinispan on Kubernetes has been described by practitioners as “a full-scale engineering project” in its own right (Palark). Every major cloud, by contrast, offers a managed Redis-compatible service: AWS ElastiCache and MemoryDB, Azure Cache for Redis, GCP Memorystore. Managed Infinispan, as a turnkey cloud service, does not exist.

We made a different call than the maintainers did, for the operators we serve. They made a defensible call for the project they steward. Both can be true.

What Locke is

Locke is the upstream Keycloak codebase plus one addition: a Redis cache backend behind a switch.

KC_CACHE=infinispan   # the upstream default, unchanged
KC_CACHE=redis        # Redis / Valkey / any wire-compatible store

Everything else is the Keycloak you know: same org.keycloak.* packages, same KC_* options, same kc.sh, same admin console, same database schema. When KC_CACHE=infinispan (the default), the Redis code never runs. The Redis path is entirely opt-in.

Why “Locke”

The name is a small joke with a serious point. John Locke argued that legitimate authority rests on the consent of the governed. Keycloak holds the keys to your identity layer; Locke is about who consents to the infrastructure underneath it. You already consent to your database. Locke extends the same courtesy to your cache.

Keycloak gives you the key. Locke gives you the choice.

The numbers

The obvious question is what you pay for that choice. We ran the official keycloak-benchmark Gatling harness (the AuthorizationCode browser-login flow) against a 3-pod cluster on start --optimized, on isolated cloud nodes where the load generator does not share a machine with the Keycloak pods.

The headline: the Redis backend delivers ~100% throughput parity with embedded Infinispan, within roughly 0.1% up to 250 logins per second, with zero errors on both stacks.

The trade is real and we will state it plainly. An in-process Infinispan read is a Java method call; a Redis read is a network round trip, so Locke adds a few milliseconds of read latency at moderate load (both stay under 170 ms p99 to 250 logins/sec). What you get back is resilience. When a node is lost, embedded Infinispan stalls for roughly 31 to 40 seconds rebalancing the JGroups cluster (p99 spiked to ~31 s in our runs) while requests queue; Locke keeps serving from Redis at sub-second p99. Cross-version rolling upgrades also roll under sustained load, because there is no JGroups protocol version that has to stay compatible across a mixed-version pod set.

One thing Locke does not do: it does not raise Keycloak’s realm-count ceiling. That limit is bound by the database and response serialization, not the cache, and it behaves identically on both backends. We benchmarked it and we say so.

Full methodology, per-operation latency, resilience, upgrade, and memory numbers are in the benchmark report, and we wrote up the head-to-head in detail in Keycloak on Redis: benchmarking Locke vs embedded Infinispan.

Getting there was not free

Reaching parity took seven iterations. The naive version started at a small fraction of Infinispan’s throughput, because moving per-request session writes onto a network cache is exactly the workload a remote cache is worst at. The wins came from an in-JVM L1 (Caffeine) in front of Redis with single-flight loading and pub/sub invalidation, from collapsing read-modify-write patterns into atomic operations, and from being selective about which caches get the L1 at all. The full optimization journal, including the dead ends, is public in benchmark/RESULTS.md. We will tell the more interesting parts of that story (and the bug that briefly made realm caches silently fall back to Infinispan) in a follow-up post.

What Locke is not

• Not a replacement for Keycloak. It is a packaging of it, in the tradition of Adoptium Temurin, Amazon Corretto, and Percona Server: a distribution of an upstream project, not a competitor to it.
• Not a hard fork. We carry a focused patch set (a handful of upstream files plus a self-contained model/redis/ module) on top of upstream main, and a CI job rebases and tests against upstream daily.
• Not an extension. A few upstream surfaces lock the cache mechanism (a closed mechanism enum, hardcoded cache options, an immutable property grouping, and a build-step index), so a clean SPI extension is not currently possible. We would happily retire the patch set if upstream opened those surfaces.
• Not a critique of the maintainers. See above.

Try it

Both backends ship in the same image.

# Redis backend: point it at any Redis / Valkey / wire-compatible store
docker run --rm -p 8080:8080 
  -e KC_CACHE=redis -e KC_CACHE_REDIS_URL=redis://my-redis:6379 
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin 
  ghcr.io/sky-cloak/locke:latest start-dev

Images are multi-arch (amd64 and arm64) and published to GHCR, Quay, and Docker Hub. The source, full benchmarks, and a longer-form rationale (WHY.md) live at github.com/sky-cloak/locke.

If you would rather not operate any of this yourself, Skycloak runs managed Keycloak (and Locke) for you: the choice without the on-call.

Keycloak gives you the key. Locke gives you the choice.