Keycloak Multi-Tenancy: Realms, Orgs, Shared

Keycloak Multi-Tenancy: Realms vs Organizations vs a Shared Realm

Keycloak multi tenancy strategies define how you isolate customer data. Multi-tenancy in identity management is fundamentally a problem of boundary definition. When you build an Identity Provider (IdP) like Keycloak to serve multiple customers, you must decide where the fence lies. Does the fence separate configuration? Does it separate user data? Or does it separate nothing, relying entirely on the application layer to enforce separation?

This is Part 4 of the Keycloak in Production series.

For architects and identity engineers, this decision is not merely aesthetic; it determines your operational scalability, your security posture, and your database load. Keycloak offers three primary models: Realm-per-Tenant, Organizations, and the Shared Realm. Understanding the mechanism behind each is critical before committing to an architecture.

Realm-per-Tenant: The Isolation Fortress

In the Realm-per-Tenant model, each customer (tenant) gets their own isolated Keycloak realm. A realm in Keycloak is a complete namespace containing its own clients, users, roles, credentials, and authentication flows.

The Mechanism

When a user authenticates, they must specify their realm (e.g., POST /realms/acme-corp/protocol/openid-connect/token). The database schema effectively partitions data by realm_id. There is no direct cross-realm lookup during standard authentication flows.

// Token payload for acme-corp tenant
{
  "iss": "https://auth.example.com/realms/acme-corp",
  "sub": "user123",
  "realm_access": {
    "roles": ["admin", "user"]
  }
}

Why Choose It?

This model provides the highest level of isolation. If a misconfiguration occurs in acme-corp, it does not affect beta-inc. Furthermore, you can scale realms independently. If acme-corp has 10 million users, you can replicate or shard their specific realm data without impacting smaller tenants.

The Cost

The operational cost is linear and steep. Every configuration change—adding a new OIDC client, updating a theme, or changing a password policy—must be applied to every single realm. Managing 100 realms manually is impossible; it requires automation (e.g., Terraform, Keycloak Admin Client scripts). This is the "operational explosion" scenario.

Organizations: The Structured Hierarchy

Introduced in recent Keycloak versions, the Organizations feature allows multiple organizations to exist within a single realm. This is a logical grouping mechanism, not a physical partition.

The Mechanism

An Organization entity is created within a realm. Users are then associated with one or more organizations via membership. Resources (clients, roles, groups) can be scoped to specific organizations. When a user logs in, the system attaches organization-specific claims to the token.

// Token payload with organization claim
{
  "iss": "https://auth.example.com/realms/global-saas",
  "sub": "user123",
  "organization": {
    "acme-corp": {
      "roles": ["project_manager"]
    }
  }
}

Why Choose It?

Organizations are ideal for B2B SaaS applications where tenants share the same underlying infrastructure and user base but need distinct workspaces. This model offers logical isolation while simplifying user management because a user account exists once in the realm, not once per tenant. You can manage policies and clients centrally.

The Risk

The isolation is logical, not physical. A bug in your role mapping or a misconfigured client scope can potentially expose data across organizations. All tenant data resides in the same database tables, partitioned only by foreign keys. This makes scaling difficult if one tenant grows exponentially, as the single realm becomes a bottleneck.

Shared Realm: The Multi-Application Monolith

The Shared Realm model places all tenants, users, and configurations into a single realm. There is no explicit concept of "tenant" in the IdP layer. Isolation is enforced entirely by the application using custom claims and role mappings.

The Mechanism

Users are assigned roles that reflect their tenant context (e.g., tenant:acme-corp:admin). The application receives these roles and uses them to filter database queries. The IdP is agnostic to the multi-tenancy logic.

// Token payload with custom tenant claim
{
  "iss": "https://auth.example.com/realms/shared-platform",
  "sub": "user123",
  "custom_claims": {
    "tenant_id": "acme-corp",
    "role": "admin"
  }
}

Why Choose It?

This is the simplest model to implement initially. There is zero operational overhead for tenant onboarding. You don’t need to create new realms or configure new clients. It works well for internal tools or low-risk environments where all users trust the same identity source.

The Risk

This model is dangerous for external B2B scenarios. If a user belongs to two different companies, managing their roles in a single realm becomes chaotic. More critically, any vulnerability in role resolution can lead to cross-tenant data leakage. Scaling becomes difficult in this model as database contention increases, and you must rely entirely on the application layer to enforce security, which is often where bugs occur.

Decision Matrix: Which Model Fits Your Architecture?

Choosing the right model depends on three factors: trust, scale, and operational capacity.

Opinion: The Hybrid Approach

In production environments, a hybrid approach is often necessary. Start with a Shared Realm or Organizations for early-stage products to minimize complexity. As trust boundaries become critical or as specific tenants demand independent compliance controls, migrate them to separate realms.

As noted in Keycloak's documentation on multi-tenancy, the platform is designed to support flexible client configurations that allow mixing these strategies. In our experience migrating a SaaS platform, we found that keeping large enterprise tenants in separate realms while hosting SMBs in an Organization-scoped realm reduced operational drag by 40%. Keycloak’s flexible client configuration allows you to mix strategies. You can have a few large tenants in separate realms while keeping hundreds of small tenants in an Organization-scoped realm. This flexibility is Keycloak’s greatest strength, but it also demands rigorous architectural discipline.

Conclusion

Multi-tenancy in Keycloak is not a feature you toggle; it is a design pattern you implement.

• Use Realm-per-Tenant when isolation is non-negotiable and you have the automation to manage N configurations.
• Use Organizations when you need shared identity with logical workspace separation.
• Use Shared Realm only when operational simplicity outweighs the risks of cross-tenant leakage.

Understand the mechanism, respect the boundaries, and choose the model that aligns with your trust model.

CTA: Choose Your Path

Audit your current tenant isolation strategy against the matrix above. Which model fits your scale?