Keycloak Multi-Tenancy: Realms vs Organizations
I'd heard Keycloak gets weird with many realms. So I benchmarked it. It does.
I’d heard repeatedly that “Keycloak gets weird with many realms,” but I never had concrete numbers to back it up. If you’re building multi-tenant SaaS on Keycloak, you’ve got two options: the classic realm-per-tenant model, or the newer organizations feature (KC 26+) that keeps every tenant in a single realm. Conventional wisdom says realms-per-tenant doesn’t scale, but by how much, and where does it actually fall over?
So I wrote a small benchmark to find out. A docker-compose stack, a REST seeder, three k6 workloads, and a sweep driver that walks tenant counts from 1 to 1500 in both modes. Everything runs on a single laptop (Ryzen 7640U, 60 GB RAM, Keycloak 26.0 with Postgres). The absolute numbers will shift on other hardware; the shape of the curves won’t.
The headline: the admin API collapses
The admin API (listing realms, fetching realm metadata, listing users) is what the admin console hits on every page load. In realms mode it degrades catastrophically: throughput drops four orders of magnitude as you add tenants, and p95 latency goes from 2 ms at one tenant to 16.6 s at 500. By 1000 realms, requests just time out.
Organizations mode actually starts slower at N=1 (fewer optimisations in the per-org code path) but stays essentially flat all the way through 1500 tenants.
Provisioning is brutal too
Same story for tenant onboarding. Seeding each tenant through the standard admin REST API (two clients, a handful of roles and groups, ten users), at N=1000 realms mode took 59 minutes. Orgs mode took 84 seconds, a 42× gap, and the realms curve is super-linear.
And then it ran itself out of memory
This was the one I didn’t expect. Somewhere around 1200 realms, during seeding, Keycloak’s ClearExpiredUserSessions scheduled task started iterating every realm on every tick, and each call rehydrated the realm cache. Within minutes, process RSS went from ~1 GB to 43 GB (72 % of the box) and CPU pegged at 600 %. I killed it. Orgs mode at 1500 tenants sits at the same ~880 MB it used at one.
What I take from it
For realm-per-tenant multi-tenancy on a single node, Keycloak isn’t viable much past ~500 tenants, and the failure mode beyond that is a hard one (OOM, not just slow). Organizations mode holds up. The user-facing bits (token issuance, JWKS) degrade gracefully in both modes, so this is really an admin-plane and provisioning problem, not a login one.
If you need true realm-level isolation, you’re not wrong to want it, you just can’t do it single-node at scale. Everyone else: reach for organizations.
The full write-up (all the workloads, cold-vs-warm numbers, sizing suggestions, and the caveats: single-node only, plain HTTP, default Postgres) plus the reproducible setup is in the repo. There’s even a Claude Code skill that runs the whole sweep for you.
github.com/franzos/keycloak-benchmark
Do take the absolute throughput figures with a grain of salt, they’re from one laptop, one KC release. The realms-vs-orgs delta is the part that travels.