How to do multi-tenant with Keycloak
When people want to achieve multi tenancy on Keycloak, they often have 2 main ways :
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.
Easy to reason about
Make sure that the usecase 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 dealed 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.
The other way is to keep everybody in the same realm and create a Keycloak client for each tenant (with its client scope).
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.
Keycloak client configuration managed will need to be automated through Keycloak admin REST API calls.
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 usecase 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 dealed 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
Keycloak client configuration managed will need to be automated through Keycloak admin REST API calls.
Updated on: 07/11/2022
Thank you!