Keycloak multi-tenancy: many organizations on one installation
Keycloak multi-tenancy comes in two forms: a realm per tenant, or organizations inside one realm. Organizations share one configuration and separate membership, so Keymate recommends them for a platform with many customers. Keymate adds nesting, delegated administration that follows the hierarchy, and an active organization in every token.
Realms and organizations
An organization is a tenant inside a realm: its own members, identity providers and administrators, on configuration the whole realm shares. Keycloak organizations have been supported since version 26.0. Keymate builds on them rather than replacing them.
Many teams build their first Keycloak multi-tenant setup as a realm per customer, because the documentation introduces the realm first. The cost appears later: every shared client, flow, mapper and role exists once per realm, and every change to them is made once per realm.
Realm vs organization: which to use when
Which one to use comes down to what differs between tenants. If tenants differ in who belongs to them and how their people sign in, use organizations. If tenants differ in how the system itself behaves, use realms.
| What differs between tenants | Organizations in one realm | A realm per tenant |
|---|---|---|
| Members and their roles | Yes, separate per organization | Yes |
| The identity provider each tenant signs in with | Yes, one or more per organization | Yes |
| Administrators who manage only their own tenant | Yes, with delegated administration | Yes, with per-realm admin roles |
| Applications (clients) | Shared: register once, used by every tenant | Registered again in each realm |
| Authentication flows and password policy | Shared | Separate |
| Token signing keys and issuer address | Shared | Separate |
| A user who belongs to several tenants | One account, several memberships | One account per realm |
| A change made for every tenant | Made once | Made once per realm |
The two can be combined in one installation: for example, one realm for all business customers, each an organization, and a separate realm for a tenant that must have its own signing keys.
How tenants are kept apart
Keymate is a multi-tenant IAM platform. Tenants can be the customers of a B2B SaaS product or the subsidiaries of a group. Keymate keeps them apart at four points: membership, administration, tokens and requests.
Membership.
A user joins an organization only when an administrator adds them, they accept an invitation, or they sign in through its identity provider. Each member list shows only that organization's members.
Administration.
A delegated administrator sees and manages only their own organization and the organizations nested under it.
Tokens.
Every token names the organization the user is acting for, so an application never has to guess the tenant from a URL or a header.
Requests.
On every request, the decision point compares the organization in the token with the organization that owns the data. The enforcement point (the Access Gateway, when one is deployed) lets the request through only when the answer allows it. A deployed Access Gateway also applies rate limits per tenant.
Every organization's users live in the same Keymate installation and database. If a tenant's contract requires physically separate data, give that tenant its own installation.
Nested organizations in Keycloak
Nested organizations let an organization contain other organizations, so a customer's subsidiaries, regions or departments each get their own boundary inside the customer's. Keycloak 26.8 has no nested organizations: an organization can hold groups with roles, but not another organization. Keymate adds that hierarchy.
Take a Keymate hierarchy of Acme, then Acme EMEA, then Acme EMEA Finance. Each sub-organization has its own members and administrators. An Acme EMEA administrator manages Acme EMEA and Acme EMEA Finance, and nothing in Acme's other regions. Use a sub-organization when a unit needs its own administrators or identity provider. Use a group for departments and teams that only need shared roles.
New tenants and sub-organizations can start from a tenant template. Creating or changing an organization emits a lifecycle event your other systems can act on.
Delegated administration per tenant
Delegated administration lets a customer's own administrator manage their organization's users and roles, and nothing outside it. Since Keycloak 26.7, fine-grained admin permissions cover organizations, so Keycloak itself has per-organization admin rights.
Keymate makes delegation follow the hierarchy: a parent organization's administrator manages every sub-organization under it, without a separate grant for each. You set the limits once: which roles a customer administrator may hand out, which settings they may change. Their changes are recorded like yours.
Tokens that carry the active organization
Keycloak organizations already put membership into tokens through an organization claim. A user in several organizations, such as a consultant working for two customers, needs one more thing: one active organization for the session, which they can change.
In Keymate, that user can switch organizations in the same session without signing in again. The new token is issued through token exchange. The active organization travels in the session and in every token, so applications and policies know which customer's data is in play. Each switch is recorded in the audit log.
Moving from one realm per tenant to organizations
Move one tenant at a time. The realms you leave keep running until their last user has moved. The order that works:
- Create one realm for all moved tenants and register your applications in it once.
- Create an organization per tenant from a tenant template, and link each tenant's identity provider to its organization.
- Move the tenant's users and role assignments into its organization through the admin API; a realm export gives you the source data.
- Change applications that read the tenant from the token issuer address, which contains the realm name, to read the organization claim instead. Applications that already read the tenant from a claim need no change.
- Point the tenant's sign-in at the new realm and retire its old realm.
Moving tenants from another IAM product, rather than between realms, is covered on Parallel Run.
Further reading
- Multi-tenancy and delegated administration: why tenants and org trees belong outside role names, three levels of delegated administration, and a sample policy that checks a tenant and an org path.
- What is Keycloak: an introduction to Keycloak's core concepts, including the realm as a tenant boundary.
Questions
What is the best way to do multi-tenancy in Keycloak?
For most platforms that serve many customers, use organizations inside one realm: they share one configuration and separate membership, so a change made for every tenant is made once. Use a realm per tenant only where a tenant needs its own signing keys, login flows or password policy. Keymate builds on organizations and adds nesting, delegated administration that follows the organization hierarchy within limits you set once, and an active-organization switch that travels in the session and in every token.
Keycloak realm vs organization: which should I use?
Use organizations when tenants differ in who their members are and how they sign in; use realms when tenants differ in how the system behaves, such as signing keys, authentication flows or password policy. Organizations let you register an application once for every tenant; realms make you register it again in each one. The two can be combined in one installation.
Does Keycloak support nested organizations?
Not as of Keycloak 26.8: an organization can hold groups, and those groups can carry roles, but an organization cannot contain another organization. Keymate adds nested organizations, so a customer's subsidiaries or departments get their own members and administrators inside the customer's boundary, and an administrator of a parent organization manages the sub-organizations under it.
Can each tenant have its own administrators in Keycloak?
Yes. Since Keycloak 26.7, organizations are a resource in fine-grained admin permissions. Keymate adds delegation that follows the organization hierarchy and limits you set once, such as which roles a tenant administrator may hand out, and records their changes like yours.
Are tenants' data separated in a multi-tenant Keycloak installation?
Not in storage: all organizations live in one database. Organizations separate access, which covers membership, administration, tokens and the decision on every request. If a tenant must have physically separate data, give it its own installation.