To understand this pattern, we first need a clear picture of what a “realm” and a “tenant” each mean on their own.

What is a realm?

A realm is Keycloak’s built-in isolation boundary. Every realm manages its own users, credentials, roles, groups, clients, and login screens, completely separately from every other realm on the same server. Two realms never share a user database, even if two people in different realms happen to use the exact same email address — Keycloak treats them as entirely unrelated identities.

What is a tenant?

A tenant is a business concept, not a Keycloak concept — it simply means one distinct customer, organization, or client using a shared platform. A software-as-a-service product that serves hundreds of companies, where each company’s data and users must never mix with another’s, has hundreds of tenants.

Putting the two together

Realm-per-Tenant architecture is the design decision to give each tenant its own dedicated Keycloak realm. Tenant “Acme Corp” gets the acme realm, tenant “Globex Inc” gets the globex realm, and so on — all running on the same physical Keycloak deployment, but with Keycloak’s native isolation doing the heavy lifting of keeping them apart.

A realm-per-tenant deployment is built from a handful of moving parts that repeat, once per tenant, across the same Keycloak instance.

How the application routes requests to the right realm

Because every realm has its own distinct login and token endpoints, the calling application — or a gateway in front of it — needs to know which realm a given request belongs to before it can authenticate. This is commonly resolved from a subdomain (acme.myapp.com), a custom domain mapped to a specific tenant, or a path segment, and then used to pick the correct realm’s OpenID Connect configuration for that request.

flowchart LR
    A[Request: acme.myapp.com] --> B[Tenant Router]
    C[Request: globex.myapp.com] --> B
    B -->|acme| D[Realm: acme]
    B -->|globex| E[Realm: globex]
    D --> F[(Acme Users, Roles, Clients)]
    E --> G[(Globex Users, Roles, Clients)]
        

“Isolation” is a word that gets used loosely — Keycloak’s realm boundary is specific about exactly what it separates.

What this means for a single human being

If the same person is genuinely a member of two different tenants — say, a consultant who works with both Acme and Globex — Keycloak treats them as two completely separate identities, one per realm, even if both accounts use the same email address. There is no automatic linking between them. Any experience where “the same person” needs to move between tenant realms has to be deliberately built, typically using realm-to-realm identity brokering.

Onboarding a new tenant in a realm-per-tenant system follows a repeatable sequence — and automating it well is what separates a smooth-scaling platform from a painful one.

The master realm should never host application users

Keycloak’s built-in master realm exists purely to administer the server itself and to create and manage other realms — it is not meant to hold application end users or application clients. Mixing tenant users into the master realm undermines the entire isolation model the architecture is built around.

Identity brokering between realms needs deliberate design

When the same human legitimately needs access to more than one tenant realm, the natural solution is to configure one realm as an identity provider for another, letting a user “sign in with their other realm’s account.” Left at Keycloak’s defaults, this can present the user with a confusing choice of login method every time, so production systems typically add custom logic to keep this transition invisible and predictable — without ever weakening the underlying separation between the two realms’ data.

Automating realm provisioning safely

Because new realms are usually created programmatically, the automation itself becomes a security-sensitive component. The credentials or service account used to call Keycloak’s Admin REST API for realm creation should be tightly scoped and audited, since it effectively has the power to create a brand-new isolated tenant space on demand.

Per-realm event visibility

Keycloak records login events, failed attempts, and admin actions scoped to the realm in which they occurred, which naturally supports giving each tenant’s own administrator visibility into only their own realm’s activity — a useful property for both operational monitoring and customer-facing audit trails.

Watching the realm count itself as a metric

Since Keycloak’s own performance characteristics can shift as the number of realms on a single deployment grows into the hundreds or beyond, tracking total realm count over time — alongside login latency and admin console responsiveness — gives an early warning before the platform approaches limits that would require splitting tenants across multiple Keycloak deployments.

Monitoring automated provisioning

Because new tenants are typically onboarded through an automated pipeline calling the Admin REST API, that pipeline’s own success and failure rate deserves its own monitoring — a silently failing tenant-provisioning job is a business-impacting incident, not just a technical one.

Common mistakes to avoid

Beyond the two anti-patterns above, teams frequently underestimate how much tenant-specific configuration drift accumulates over time — a template realm updated for new tenants doesn’t retroactively update existing ones, so a process for propagating shared policy changes (like a new password requirement) across every existing tenant realm needs to exist from the start. It’s also easy to forget that SSO does not span realms by default; assuming a logged-in session in one tenant realm will be recognized in another is a frequent source of confused bug reports.

No. The other common pattern keeps every tenant in one shared realm and uses a separate Keycloak client per tenant, relying on role-based access control for isolation instead of realm boundaries. It trades some isolation strength for significantly better performance at very high tenant counts.

Yes, but Keycloak treats them as two completely separate identities with independent credentials and lifecycles, even if the email address is identical. Linking them into a smooth single experience requires deliberate identity-brokering configuration.

There’s no hard limit, but real-world reports and documentation note measurable performance drops once a deployment reaches several hundred realms, though this has improved across newer Keycloak versions. Load-testing at your expected scale is the only reliable way to know your own limit.

No. The master realm is reserved for administering the Keycloak server and other realms. Application users and clients should always live in their own dedicated realms.

No. Single sign-on in Keycloak applies within one realm only. A user authenticated in one tenant’s realm is not automatically recognized in another tenant’s realm without explicit identity brokering set up between them.

Realm-per-Tenant architecture gives every customer on a shared Keycloak deployment their own fully isolated identity space — separate users, roles, clients, login flows, and identity provider connections — while still running on one underlying server. It is the strongest isolation option Keycloak offers for multi-tenancy, and the easiest to reason about during a security review, but it trades that strength for real operational overhead: realm provisioning has to be automated, shared users across tenants need deliberate brokering, and very large tenant counts can strain a single Keycloak deployment’s performance.