SaaS Multi Tenant Approaches Using Keycloak

What is Multitenancy in Identity Management?

In today’s cloud-native applications, multitenancy is becoming increasingly essential, especially when you want to provide services to multiple organizations, departments, or clients from a single platform. This is a core pattern in our Multi-Tenant Platform Development work. Multitenancy in SaaS Identity Management allows different tenants (e.g., organizations or groups) to have separate user bases and configurations within the same instance of an identity provider, in this case Keycloak.

Keycloak is an open-source identity and access management tool, that provides single sign-on (SSO), authorization, and identity management for modern applications. It supports OAuth2, OpenID Connect (OIDC), and SAML, making it ideal for cloud-native identity management solutions.

In this post, we’ll explore several approaches that we use at Afriq Silicon for implementing multitenancy using Keycloak (OIDC). This post assumes that you have some basic knowledge about Keycloak terminologies.

Multitenancy Approaches in Keycloak

1. Separate Realms Per Tenant

This is one of the most straightforward ways to achieve multitenancy in Keycloak, especially when strong isolation between clients is required. Each tenant gets its own Realm. In Keycloak, a realm is a separate namespace where you can manage users, roles, clients, and authentication flows independently of other realms.

Advantages:

• Since a realm can have its own authentication settings, this means strong isolation between tenants, allowing for custom configurations, branding, and login flows.
• Ideal for scenarios where different tenants require significant differences in user management policies or authentication protocols. The realm ID can also be used across databases as the tenant/organization ID.

Drawbacks:

• As the number of tenants grows, managing realms can become more complex, and as such, resource consumption may increase, as each realm needs to maintain its own set of users, roles, and configurations.

2. Shared Realm with Tenant-Specific Roles or Groups

In this approach, a single realm is used for all tenants, with differentiation achieved through Roles or Groups. Each user is assigned roles or added to a group based on the tenant they belong to. You can also configure tenant-specific access control policies, by using groups or roles. In this case, the tenancy ID used across databases can be configured through properties.

Advantages:

• Easier to manage than having multiple realms. Additionally, shared configuration reduces overhead when maintaining the system.

Drawbacks:

• Limited isolation between tenants and their information. This approach requires complex authorization rules to manage tenants within a single realm.

3. Partitioning with Realms and Clients

In this approach, you create separate clients (applications) for each tenant but manage them within a single realm. Each tenant’s users interact with their specific client, hence isolating the client-level settings like redirect URIs, roles, and login configurations. In this use case, the tenant-specific identifier across databases is the client ID set in Keycloak.

Advantages:

• This method of multitenancy creates isolation at the client level, thus easier to manage and maintain downstream.

Drawbacks:

• Clients share some configurations and resources in the realm, so full isolation may not be possible, especially in microservice architecture due to auth leaks within the realm.

4. Using Keycloak’s Identity Provider Federation for Multitenancy

In some cases, you may want to delegate authentication to external identity providers for each tenant (e.g., LDAP or another SSO provider). Keycloak supports identity federation, which allows each tenant to authenticate using their external identity providers while still centralizing user management in Keycloak. This is best used in cases where clients have their own identity providers and needs a central auth integration.

Advantages:

• Each tenant can bring their own identity provider of choice, which enables great flexibility in integrating with external user directories like those provided by cloud providers like AWS.

Drawbacks:

• External identity providers can complicate the setup and add potential points of failure.

Best Practices for Implementing Multitenancy in Keycloak

1. Automate tenant provisioning. Managing realms, clients and users by hand gets cumbersome quickly at scale, so use Keycloak’s Admin REST API to create and configure tenants programmatically.
2. Plan for resource use. Large-scale multitenancy benefits from clustering and horizontal scaling of Keycloak itself, particularly if you have chosen the realm-per-tenant approach.
3. Enforce isolation through RBAC. Use Keycloak’s role-based access control to keep tenants separated, and enable SSO within each tenant while keeping tenants isolated from one another, so users face fewer authentication prompts without weakening the boundary.
4. Monitor each tenant separately. Log and monitor tenant interactions through tools that integrate with Keycloak, such as Prometheus and Grafana, so that performance problems and errors can be traced to the tenant they affect.