Keycloak multi-tenancy architecture [en]

June 12, 2024

What is a multi-tenant architecture?

In a cloud infrastructure, a multi-tenant architecture means that several customers share one installation. This mutualization generally enables economies of scale.

First, we'll compare it with the simple tenant approach, then detail the advantages and limitations of multi-tenant architectures with Keycloak. Finally, we'll show how SaaS solutions for hosting Keycloak can meet these challenges.

Reminder of simple tenant architecture

In this architecture, a Keycloak installation is associated with a single tenant and application. Each of these deployments has its own domain and connection theme.

Pro : 

  • Basic and simple architecture

Cons :

  • The cost of scaling a simple architecture remains. A whole new Keycloak stack must be maintained for each new application. Servers, databases, networks… As a reminder, by 2023, Keycloak will have 18 versions, including 3 major ones, so that's as many maintenance operations to multiply by tenants. For 3 tenants, that's 54 Keycloak updates!

  • Duplication of user identities. Centralized identity management becomes complex if the user needs to access different organizations. The user experience is also degraded: the user must juggle several passwords for the same email address. To overcome this, it is necessary to develop a synchronization overlay.

A multi-realm concept

Multi-realm architecture means that a single Keycloak instance contains one realm per tenant.


  • Pool efforts and costs by bringing all your tenants and users together in the same deployment. 

  • Users only have access to their realm and do not see customers from other realms.

  • This is the simplest approach, as multi-kingdom architecture requires less development time for functional implementation.


  • For each realm, a user will have a distinct identity. If a user shares multiple identities in multiple realms, it becomes very complex to link them.

  • Like all software, Keycloak has known limits. Performance is degraded beyond a hundred or so realms: start-up, use of the administration console, creation of entities such as realms, etc. This problem is an issue identified by the project.

  • The load effects on one component will affect all the others:  I/O, memory, network, everything is shared.

The multi-client concept

Multi-client architecture means a single realm for all users and stakeholders. With this architecture, the management of user roles is delegated to the application. By default, all users are able to "see" all clients within the realm.


  • Pooling of efforts and costs by bringing together all stakeholders and users within the same deployment. 

  • Better scalability: it's possible to have several thousand customers in a kingdom, unlike kingdoms limited to a hundred or so for performance reasons.


  • Part of managing user rights is delegated to the client, which requires customization of the Keycloak deployment to achieve stricter partitioning.

  • Roles are configured via the label concept in Keycloak, but it is impossible to configure roles for each tenant.

  • The application must react to each label, check the rights assigned, and manage user access according to their rights. You need to be able to block access to the application completely for users who don't have the right access rights.

Promising alternative for Keycloak v25

Keycloak v25 will introduce a concept of organization within the kingdoms that will act as tenants.

The organization concept reinforces partitioning within a deployment. Tenants containing users can be grouped within an organization. Creating several organizations within a single realm will be possible, adding more depth to realms. 

Cloud IAM, the best of both world?

For obvious security reasons, our architecture is single-tenant, enabling us to isolate our customers completely. In the event of a problem or outage, this will not impact all our customers. Our product and our expertise enable us to deploy, observe and maintain hundreds of Keycloaks in operational condition every day.

When it comes to multi-tenancy at Cloud-IAM, we have two options:

  • Simplicity: some of our customers prefer to use multiple deployments with Cloud IAM. Keycloak management is entirely our responsibility. They appreciate the benefits of a single tenant without the problems, all at a very competitive cost.

  • Tailor-made: some of our customers build their own configuration based on the multi-tenant / multi-client architecture mentioned above. Our experts help them to configure and deploy the architecture in their specific case.
Written by
Last update :
William PIERRE
June 12, 2024