Keycloak Multi-Tenancy: A Complete Guide

Last updated: March 2026

In the diverse world of software security and identity management, the topic of multi-tenancy in Keycloak is much like a religious debate, split between two main schools of thought: Monorealmism and Polyrealmism.

This distinction can be paralleled to theological perspectives — just as in religion where beliefs and practices can vary vastly, in Keycloak, the approach to handling multiple tenants can differ significantly, leading to a variety of strategies.

Monorealmism

In the Monorealmistic view, there is a single, all-encompassing realm that governs the authentication and authorization processes across all applications and services. This singular realm approach simplifies the management by having a centralized set of users, roles, clients, and settings. Configuration under Monorealmism typically involves setting up one realm to cover all necessary aspects of authentication and authorization, utilizing fine-grained permissions and role-based access control to separate different user groups and services.

Polyrealmism

Conversely, Polyrealmism advocates for the use of multiple realms within Keycloak. Each realm acts as an independent entity with its own set of users, roles, clients, and configurations. This approach aligns with a more compartmentalized view, where each tenant or project has its own realm, allowing for tailored authentication flows, user management, and isolation between different parts of the business or various external clients.

Which one is Best for Multi-Tenancy?

Choosing between Monorealmism and Polyrealmism can be challenging. To assist in this decision, here is a comparative table outlining the pros and cons of each approach:

When to Choose One Over the Other

• Monorealmism is best suited for scenarios where all users are part of the same organizational unit and where there is no strict requirement for tenant isolation. It’s ideal for smaller organizations or in-house applications where simplicity and ease of management are prioritized.
• Polyrealmism, on the other hand, shines in environments requiring high levels of tenant isolation, such as in multi-tenant SaaS applications, or where different departments or groups require distinctly different authentication workflows and settings. It’s suited for larger, more complex organizations or service providers.

Overcoming the Cons of Monorealmism

Monorealmism, while providing simplicity and consolidated management, often faces criticism for its lack of tenant isolation and scalability challenges when adapting to varied tenant needs. However, these limitations can be significantly mitigated through strategic approaches and technological solutions.

One effective method to enhance the Monorealmistic approach is by utilizing extensions such as keycloak-multi-tenancy. This tool allows for a single realm to host multiple tenants while enabling a level of isolation and customization that is typically only seen in Polyrealmism.

Organizations Feature in Keycloak (Now GA)

The Keycloak Organizations feature, introduced as a preview in Keycloak 25 and now generally available since Keycloak 26, provides first-class support for multi-tenancy within a single realm. This is a major step forward for teams looking to implement B2B identity management without the complexity of managing hundreds of realms.

With the Organizations feature, you can:

• Create organizations within a realm: Each organization acts as a logical tenant with its own members, identity providers, and invitation workflows.
• Assign users to organizations: Users can belong to one or more organizations, with organization-specific roles and attributes.
• Configure organization-specific IdPs: Each organization can have its own federated identity provider (e.g., a customer’s corporate SSO), enabling seamless B2B federation.
• Manage organization membership: Invite users, manage memberships, and control access at the organization level.

To enable Organizations in Keycloak 26+, navigate to Realm Settings > General and toggle Organizations to ON. For full details on configuration, see the Keycloak Organizations documentation.

For a deeper dive into how the Organizations feature works in practice, see our dedicated article on multitenancy in Keycloak using the Organizations feature.

Overcoming the Cons of Polyrealmism

While Polyrealmism presents challenges, notably in terms of configuration complexity and management overhead, these can be mitigated. Tools and strategies, such as centralized management software, can streamline the handling of multiple realms. Automating setup and synchronization across realms can also reduce the administrative burden.

With Skycloak’s managed hosting, the operational complexity of managing multiple realms is handled for you — including automated backups, updates, and monitoring across all your realms. This lets you focus on your application logic rather than infrastructure management.

Conclusion

The choice between Monorealmism and Polyrealmism in Keycloak multi-tenancy resembles choosing a path based on beliefs and requirements. With the Organizations feature now GA in Keycloak 26+, the Monorealmism approach has become significantly more viable for B2B use cases that previously required Polyrealmism.

With the right tools and strategies, the drawbacks of each approach can be managed, leading to a secure and efficient identity and access management system. Consider your isolation requirements, scale expectations, and operational capacity when making this decision.

To explore how Skycloak can simplify your multi-tenant Keycloak deployment, check out the pricing page or read the documentation for architecture recommendations.