Multi-Tenancy - realm resolution based on username (email address)


We’re trying to create a SaaS with multi-tenancy, and would like to extract the tenant information (and hence the Keycloak realm to use) based on the username the user is trying to login as.

Is that possible? How?


Determining the realm during login

Deciding which tenant a login belongs to can be done by either putting the tenant information in the application hostname, e.g. or by looking at the username entered by the user, e.g.

And we’d like to extract the tenant/realm from the username entered. But how do we get around the chicken-and-egg situation, where we need to include the realm in the Keycloak URL but the realm is only known after the user has entered his username on the Keycloak server?

The Multi Tenancy documentation has a code example that shows code selecting a tenant based on path and realm variables. First of all I think path and realm are undefined in the example (tracked separately in KEYCLOAK-15065). But more importantly, the only input to:

public KeycloakDeployment resolve(OIDCHttpFacade.Request request)

is the HTTP request, so it doesn’t reveal how it is possible to extract the tenant/realm from the username. My guess is also that this method is called before the username has been entered by the user.

Multiple Keycloak Instances are Required

Further, Multi Tenancy says:

Multi Tenancy, in our context, means that a single target application (WAR) can be secured with multiple Keycloak realms. The realms can be located on the same Keycloak instance or on different instances.

And because of limitations on the number of realms per Keycloak instance we should be prepared to have multiple Keycloak instances since we will have many tenants and hence many realms.

So when the user hits the login link, we need to know both the Keycloak server and realm immediately in order to create the Keycloak URL, but the user hasn’t entered his username anywhere yet, so we don’t have any information to go on.

Please help! We’d hate to conclude that due to a Keycloak limitations, tenant determination is only possible based on application hostname , e.g. not by looking at the username entered by the user, e.g.

Application Dialog won’t work with SSO

Before anybody suggests just to add a dialog box in the application asking for the username, determine realm and Keycloak server from that and then redirect to Keycloak using the login_hint GET param from the OIDC spec: That won’t work with SSO, where if the user is signed in applicationA and tries to login to applicationB, she should not be shown any dialog box at all, just be logged in immediately to applicationB. And only the correct Keycloak server knows whether the user is already logged in :frowning:


Ok, so are you guys ready for a hack? If you have a better solution, I’d still love to hear about it.

Keep in mind that because of KEYCLOAK-4593 if we have > 100 realms we may need multiple Keycloak servers also.

We’ll need:

  • A separate HTTP server specifically for this purpose,
  • An algorithm to determine the Keycloak server and realm from a username (email address).

Here would be the entire OAuth2 Authorization Code Flow:

An application discovers the user wants to log in. Before multiple realms, the Keycloak server and the realm’s name would be a constants, so the application would redirect to:$get_params

Instead, it redirects to$get_params

auth-redirector determines if it itself has a valid access token for this session, perhaps having to refresh the access token first from the Keycloak server that issued it (the user could have logged out and is trying to login as a different user that is served by a different realm).

If it has an valid access token we can determine the Keycloak server and realm from the username or email address in the access token and redirect to:


from here, the OAuth2 Authorization Code Flow proceeds as usual.

Else if it doesn’t have a a valid access token, the auth-redirector stores the original app’s $get_params as session data. It presents a form to the user asking for a username. When the user submits that, we can determine the Keycloak server and realm to use and then auth-redirector itself logs in to the Keycloak server using its own $get_params. Once the auth-redirector gets a call-back, it retrieves the access+refresh token from the Keycloak server and stores them in session data. It then, finally, redirects back to that same keycloak server and realm with the callers original $get_params (from session data). And the OAuth2 Authorization Code Flow proceeds as usual.

This is definitely a hack! But I think it could work. I’d love to try it out some day, time permitting.

Other hacks/solutions are needed for other OAuth2 flows…

This is a cross-post of my Stack Overflow answer

1 Like

This post includes a discussion of some approaches:

Manual Selection Before Authentication

This is when you have an extra field on your log in form where the user would manually type in their Organization. They might type in “Green” for the Organization that they belong to, and then enter their email and password as usual.

Manual Selection After Authentication

First the user would authenticate using their username and password. Then they land in the lobby of the application where they select their Organization from a list. The user would select the right one and go to the main part of the app.

Automatic Selection by Subdomain

This post will focus on the easiest type of Multi-Tenancy to manage for your users which is Automatic Selection by Subdomain. It’s an advanced Multi-Tenant feature supported by Stormpath. Let’s look at how to build this.


We have a same problem. Our cloud service is multi-tenancy and Keycloak is our IAM of choise. We have created a wrapper application that holds user configurations and specific application permissions. That part of the system has a task to identify a user organization based on email domain, check if exists and make redirect to the correct organization realm where user must insert password, otherwise user login will failed. System must guarantee that user email is unique! In Keycloak user in the same realm must have different emails, not between realms which is the main problem with Keycloak user management, in our use case.

The approach isn’t the simplest one but it works and probably all custom IAM servers inside companies with multy-tenancy cloud services are working in that way. First step is to identify user, second step is to make password validation.

We weren’t happy to develop something that Keycloak should have, which is multi-tenancy login built-in. Anyway, Keycloak is the great piece of software and I’m happy to use it but multi-tenancy is the common scenario this days.
A problem with custom implementation in security context is that are untested.
I hope in the future something will change about that.


Keycloak X should offer a scalable implementation for realms - at least on paper:

The current storage layer is complex, especially when deployed to multiple-sites. It has a number of scalability issues like the number of realms and clients.

However I don’t know what is the status on that.
It is supposed to be a release on end of 2020 according to Introducing Keycloak.X - Keycloak .

Maybe @stianst or someone else from the community can give an update on Keycloak X status.
Depending on your timeline it might be something to look at.

Thanks for a tip. I didn’t know anything about that.
To be honest the latest versions of Keycloak library, that we have as dependency in our project, expose many ways of doing the same thing. I think that keycloak core team planning some changes of data model on application level. Due to API REST model evolution could be very hard, expecially when you need to keep backword compatibility.

We are in 2020 and we did what was required to have multi-tenancy in our system. If something change soon it will be greate news.


This discussion is quite old, but I decided to reuse the context for my existing issue. I’m using KeyCloak with multitenancy set up and trying to produce SaaS app. My issue sounds like a technology specific, but I found pretty hard to make an integration with Blazor, where realm (within authority Url) needs to be set upfront. I tried with several approaches (including ‘a wrapper application’ mentioned above), but looks like I’m blocked and got a stuck for a while.

I imagine having an approach, where “/common” in the authority in the URL is being used and KeyCloak would be able to determine the realm based on the email or name:

Not sure how the configuration would be handled in such a case (e.g. well-known url, which also contains realm name), but seems like it is possible to be done.

What is your opinion about it? Maybe I should totally skip multi-tenancy setup, switch to single-realm and check Fine-grained authorization? However I like the isolation on the KeyCloak’s level.


I’m also evaluating if keycloak is the right choice for our new SaaS Product, but I also don’t know how to solve this multi-tenancy issue.

I have two ideas for resolving the correct realm for a user, but I don’t know or I can’t find any resources if they are good/secure:

1. Keycloak provides a “not-realm-specific” login page and determines the correct realm based on the credentials

I hope my thoughts are correct: if a user wants to access an application, keycloak determines if a token exists and if not redirects the user to the correct login page provided by keycloak based on the configs with the pre-defined realm. This is only possible if I can ensure that the user only try to access the app where I know the realm in advance.

The most secure way would be to let keycloak determine the correct realm based on the credentials through a “not-realm” specific login page.

Does something like that exist or did I understand something wrong?

2. Provide a login page in the application context and determine the realm based on the credentials

Not really secure, because the application should not have access to the user’s credentials. If the application knows the username, there could be a logic which maps the credentials to a realm.

1 Like

For everybody interested in the solution I am trying to solve this issue: Create a custom realm that acts as a proxy between the application and all other realms.

1 Like

Hi Alex, can you please specify it a little bit more. We are seeking a solution of auto-finding the specific Realm on login.