Cloud-IAM | DOCS

Appearance

How to handle multitenant organization ​

When people want to achieve multi tenancy on Keycloak, they often have 2 main ways :

1 realm per tenant ​

The simple and obvious way. You get proper isolation with different realms, each one having potentially different login page/theme for branding for example. But it comes with some drawbacks that need to be known going down that path.

Pros ​

  • Easy to reason about

Cons ​

  • Make sure that the use case does not imply that the same user can not access different realms at the same time. Because even if it is the same account (same email for example), it would be 2 different identities for Keycloak, having different lifecycle (it can even lead to different password for exemple, depending on the feature you activate). This kind of setup would need to setup Identity Providers between the different realms, resulting in frictions in the user experience. By default when you setup an Identity Provider (IdP), you ask the user to choose how he want to connect : on this realm, I use my login/password, on that one I sign in with my other realm account, etc. This behavior can be dealt with custom extensions in order to keep the friction low on the UX.
  • High numbers of realm leads to performance drops in Keycloak when you hit several hundred of realms, because of the technical choice done by the Red Hat teams. Even if things are going better with the new versions of Keycloak, it is still not perfect.

1 client per tenant (in 1 realm) — recommended ​

The other way is to keep everybody in the same realm and create a Keycloak client for each tenant (with its client scope).

Pros ​

  • great performance
  • every users have the technical possibility to access every application (client) of the realm, so authorization (RBAC) is needed to achieve isolation. With the configuration of the audience of the tokens with a dedicated client scope, the SSO perimeter can be limited, ie a token provided by a client won't be able to be used on another client if not configured to do so.
  • still have dedicated login branding if you want (login theme can be override on a client basis), as well as the authentication flow and some other parameters.

Cons ​