If you’re working with Keycloak and wondering how to handle multi-tenancy, then this article is for you. I’ve seen a lot of confusion around realms – what they are, how they behave, and whether they’re the right building blocks for tenant separation. Let’s break it down.
What is a Realm in Keycloak?
At its core, a realm in Keycloak is a fully isolated environment. Think of it as a mini identity provider – one that has its own users, clients, roles, authentication flows, and configurations. Realms don’t share anything, not even login pages. From a security and architecture perspective, this is strict isolation.
So here’s the key idea: Every realm = a separate identity provider (IdP).
If you’re planning to separate tenants by realm, keep this in mind – you’re not just organizing data differently, you’re literally spawning new IdPs.
Can Realms Be Used for Multi-Tenancy?
Short answer? Yes, but it’s not always pretty.
Keycloak wasn’t originally created to act as a multi-tenant identity platform. It’s extremely powerful and flexible, but multi-tenancy requires you to piece together features and sometimes fill the gaps with custom code.
At the very least, the open-source Keycloak has limitations related to Infinispan and the database layer. For unlimited scaling of your authentication product in a cloud environment, you should rely on database sharding, separate regional cloud accounts, geographical DNS load balancing, replacing RDBMS with Cocroachdb, Cassandra, and so on.
Let’s walk through the some patterns I’ve seen used in production, along with the pros, cons, and real implications of each.
Option 1: One Realm, All Tenants
Here, you treat the realm as a shared environment. All tenants’ users and clients live side-by-side. You use:
- user attributes (e.g.,
tenant_id) - groups or roles to tag users and admins
- logic in your app to enforce tenant boundaries
Upside:
- simple setup and deployment
- no need to manage multiple endpoints or IdP configs
- great for MVPs or internal tooling
Downside:
- weak tenant isolation: everything is soft-separated
- admin delegation is tough
- risk of misconfiguration increases with scale
If you need strong boundaries or compliance (HIPAA, GDPR, SOC 2), this might not cut it.
Option 2: One Realm per Tenant
This one’s straightforward: every tenant gets their own realm. Their own users, roles, clients, login flows and etc.
Upside:
- strongest isolation model possible
- clean separation of concerns
- easier to delegate admin rights per realm
Downside:
- operationally heavier: onboarding a tenant = provisioning a realm, setting up clients, configuring mappers, etc.
- your applications must support multiple IdPs, each with different OpenID Connect endpoints and issuer URIs (only if this is required to interact between different applications from different realms)
- token validation and discovery must handle multiple realms
This approach shines if you’re working with fewer, high-value tenants, say in B2B SaaS and need clean separation.
Option 3: Brokered Identity: Common Realm + Tenant Realms
This is where things get creative and more challenging. I personally don’t recommend this until you know exactly what you are doing.
You use:
- a shared realm as the entry point for your apps (“gateway or common realm”)
- separate realms per tenant, registered as external IdPs in the gateway realm via Keycloak’s identity brokering feature
Flow:
- App redirects the user to the gateway realm
- Gateway realm brokers authentication to the correct tenant realm (based on user choice or auto-discovery)
- User logs in at the tenant realm
- Auth result is returned to the gateway realm, which issues the app token
Benefits:
- Clean tenant data separation (tenant realms)
- Apps only integrate with one realm
- Easier onboarding from a client/app perspective
Challenges:
- youa are duplicating user sessions: one per realm (broker + tenant)
- shadow users get created in the gateway realm
- you likely need to build custom sync logic for user profile updates, logout propagation, and cleanup
- more moving parts, more complexity
Option 4. Organization Feature (available in Keycloak starting from version 25 and higher)
With the organization feature, it is possible to have multitenancy in one realm. It is possible to assign to organizations:
- users
- identity providers
- attributes and so on
So, let’s start Keycloak from “Keycloak cookie based SSO on real example” and check in “Server info” tab in Keycloak realm that ORGANIZATION feature is available for us.
Now create new “orgs-test” realm we are going to experiment with, and in the realm settings, enable checkbox
We now have the “Organization” element in the left sidebar, where all configurations can be managed. However, this is a separate topic that will be covered in detail later. The organization’s functionality is more suitable for working with external identity providers
Challenging pattern I’ve had to deal with
(It is not necessarily bad for security, but it is so inconvenient for developers.)
In this setup, there are multiple realms and more than one Keycloak instance. This results in multiple iss claims in JWT tokens and creates the need to support multiple issuer URIs in your resource server configuration – especially when a JWT issued by one Keycloak needs to be accepted by the resource server that is configured to trust another.
Also, there is not guarantee that all stack and frameworks will support this, for example, Spring Security supports multiple issuer URIs, but that may not be the case.
Consequences
Due to the current Keycloak limitations for scaling:
- infinispan
- RDBMS
For multi-tenancy, I would prefer to create separate Keycloak instances, each with its own database and Infinispan cluster (not in embedded mode), to better scale across different organizations. This would be managed using a GitOps approach with Terraform/Terragrunt, Ansible, the Java Admin Client, or other similar technologies.
Popular questions regarding Keycloak realms:
Q. What is the maximum supported number of realms in Keycloak.
A. It’s not programmatically limited, but be sure to carefully check the related GitHub issues – in some Keycloak versions, performance worsens as the number of realms increases.
- https://github.com/keycloak/keycloak/discussions/11074
- https://stackoverflow.com/questions/54465114/when-realm-count-reaches-around-470-keycloak-basically-becomes-unstable
Q. Does Keyclak support realm hierarchy
A. There is no such capability.
Q. Are the Keycloak and Realm CORS configurations separate?
A. Yes. You configure your CORS settings for every realm separately.
Q. Keycloak and Realm keys: Does every realm have its own pair of keys for operations like signing JWT?
A. Yes. When a new realm is created, a different pair of keys is also generated, and then these keys are used for signing JWT and validating signatures. Here is also the tricky moment for different realms, you will have different OIDC endpoints, including JWKS ones that are used for getting certs for JWT signature validation
Q. Is SSO supported for multiple realms?
A. If we are talking about cookie-based SSO, this is not supported by default. The one technique that could work is when you create a separate common realm and then federate users (OIDC, SAML) through other realms. I will try to describe this technique later. However, you can use QR code authentication or other techniques to work around this limitation. Just remember that each realm is separate IdP, and technically SSO between IdP works well, like when, for example, Keycloak is Identity Broker and ADFS is Identity Provider, but we just have separate SSO cookies set for each of IdP.
Q. How to migrate users from one realm to another?
A. Try to use Keycloak Java admin client or perform this operation on the database level with Keycloak’s downtime. If you need to have eventual consistency of users between different realms without creating code that would work with Admin REST API it doesn’t look possible.
Q. Is that possible to have one resource server that correctly handles tokens issued by different realms?
A. Yes.
That’s the gist. Hopefully, this helps you navigate the often-confusing world of Keycloak multi-tenancy.
If you found this useful, consider subscribing or dropping a comment. Got a pattern I didn’t cover?