Home realm discovery (HRD) is the step where a login system works out which identity provider a user belongs to, usually from the domain of the email address they type, and sends them straight to it. Keycloak, the open-source engine behind many identity management as a service offerings, does this with Organizations: you attach an email domain to an organization, link the organization to the customer’s identity provider, and turn on auto redirect for that domain, so that user@customer.com is sent to the customer’s own login without being shown a list of providers. This works as described in Keycloak 26.8, and the main thing to know before relying on it is that a user with a local password is asked for it rather than redirected.
This post explains the term, shows the Keycloak setup, and covers the security and failure cases that matter for a B2B SaaS where each customer brings its own identity provider.
What is home realm discovery?
The term is best known from Microsoft AD FS and Entra ID, though Auth0 and other products also use it. It describes the decision an app has to make, when it supports several sign-in sources, about which source holds each user’s account (their “home realm”). Microsoft Entra offers a home realm discovery policy and a domain_hint request parameter for this purpose. Outside Microsoft’s products the same idea is called identity provider discovery, email domain discovery or identity-first login.
For a B2B SaaS the problem is concrete. You have a hundred customers, each with its own Entra ID, Okta or Google Workspace. Showing every user a button for each customer is impractical and leaks your customer list, and asking people to pick “their company” from a dropdown is slow and error-prone. HRD removes the chooser: the user types an email address, and the system routes them.
How does Keycloak implement home realm discovery?
Keycloak does not use the name, but its Organizations feature implements the behavior. According to the Server Administration Guide for 26.8, when a realm has organizations, the browser flow defaults to an identity-first login. The user is asked for a username or email first, and Keycloak then:
- Extracts the domain from the email address, lowercases it, and looks for an organization that owns that domain.
- Checks whether that domain is configured with an identity provider and auto redirect.
- Either redirects the user to that identity provider, or continues with the normal credential step.
Domains are matched by specificity. An exact domain such as example.com matches only that value, while a wildcard such as *.example.com matches the base domain and every subdomain. If several entries match, the most specific wins, and an exact match beats a wildcard of the same length. The rules are in the Keycloak documentation on managing organization domains and authenticating members.
One version note matters if you have read older material: in Keycloak 26.8, routing moved from the identity provider link to the domain itself, so each domain has its own identity provider and auto redirect setting. On 26.7 and earlier the setting lives on the identity provider link, and step 4 below looks different.
How do you set it up?
The steps below use the admin console of a realm with Organizations enabled. Our post on multi-tenancy with Keycloak Organizations covers enabling the feature and the surrounding concepts.
- Create the identity provider for the customer, for example an OIDC or SAML connection to their Entra ID. The identity providers recipe and our guide to setting up SSO with Microsoft show how.
- Create an organization for the customer and link the identity provider to it under the organization’s Identity providers tab.
- Add the customer’s domain under the Domains tab, for example
customer.com. - Edit the domain, select the linked identity provider, and switch on Auto redirect.
- Test the flow by signing in with a test address on that domain.
Three settings on the identity provider control when its button appears on the login page. For a multi-tenant product you will normally want customer providers hidden from users whose domain did not match, which is what Hide on login page when organization not resolved does. Hide on login page hides the provider when the user is already authenticating in the organization’s scope, and Show on login page for unlinked members controls whether members linked to another provider still see it.
When should you use Organizations routing, kc_idp_hint or a custom chooser?
| Approach | Who decides the provider | Best for | Weakness |
|---|---|---|---|
| Organizations domain routing | Keycloak, from the email domain | Self-service login for many customers with one entry point | Needs the user to type an email first, and only works for domains you have registered |
kc_idp_hint |
Your application, via a request parameter | Customer-specific login URLs, links from a customer’s portal, IdP-initiated flows | Your app must know the provider before the redirect, see our guide |
| Custom login theme chooser | The user, by picking from a list | A small, fixed set of providers | Exposes the list, and does not scale to many tenants |
You can use both together. A common setup uses Organizations routing on the generic login page, and kc_idp_hint on vanity URLs such as customer.yourapp.com, so both paths lead to the same identity provider. Federated identity management for B2B SaaS shows the wider architecture, and is Keycloak right for B2B SaaS helps decide whether it fits your product.
How do you stop someone claiming a domain they do not own?
Routing relies on the domain belonging to the right organization. A realm admin can already change anything, so the real exposure is delegated or self-service onboarding of customer domains: if someone could attach bigcorp.com to their own organization, they could capture the logins of everyone at that company and, with an identity provider they control, assert any identity they like.
The 26.8 administration guide states that a domain cannot be shared across organizations in the same realm and describes the validation rules for wildcards, but it does not describe an automatic DNS ownership check. The domain API has a verified field, but Keycloak does not check DNS or enforce it, so setting it proves nothing. Treat verification as your own responsibility:
- Confirm the customer controls the domain before you add it, for example by having them publish a DNS TXT record you generate, or by requiring a signed contract and a contact on that domain.
- Restrict who can edit organizations and domains in the realm, and do not hand that ability to customers without a review step.
- Review domain changes in admin events.
- Keycloak checks that managed members and users arriving through a linked identity provider have an email on a domain routed to that provider, so set routing on every domain you register.
What about shared domains like gmail.com?
Never add a consumer mail domain to an organization. Everyone with a gmail.com address would be resolved to that organization and routed to its provider. Keycloak rejects wildcards over a bare top-level domain such as *.com, but it does not know which ordinary domains are shared, so that judgment is yours.
For users without a company domain, keep a separate path: a local account, a social login, or an invitation to a specific organization. The login page still shows these options to people whose email does not match any domain.
How do APIs know which tenant a user came from?
Request the organization scope. Keycloak then adds an organization claim listing the organization or organizations the user belongs to, and you can include the organization ID and attributes by editing the mapper. The formats are organization for a single membership (a user with several memberships is asked to pick one), organization:<alias> for a named one, and organization:* for all of them, and you cannot mix formats in one request. Your API should read the claim to authorize access to the right tenant’s data, which the guide on mapping organization claims explains.
What failure cases should you plan for?
- Unknown domain. If the email domain does not match any organization, the user sees the standard login form. Decide whether that is what you want, or whether sign-up should be closed for unknown domains.
- User already has a password. With auto redirect on, a user who has first-factor credentials in the realm, such as a password or passkey, is asked to authenticate with them rather than being redirected. This is documented behavior, and it is why leftover local passwords weaken enforced SSO. Remove local credentials for accounts that should only use the corporate provider.
- Provider outage. If the customer’s identity provider is down, their users cannot sign in. Make sure support knows how to tell the difference between a Keycloak problem and a customer IdP problem.
- Wrong or missing email claim. Routing uses the email typed at the start, but membership after a brokered login depends on the email returned by the provider and on the domain check. If a provider returns an address on a different domain, the user may be blocked at profile review, or may sign in without joining the organization.
- Account linking. By default the first broker login flow asks a user whose email matches an existing account to confirm and re-authenticate before linking. The risk is a flow changed to link automatically (for example by trusting the provider’s email), which would let a customer’s identity provider take over an existing local account, so review the flow before enabling auto redirect.
- Disabled organization. When an organization is disabled, managed members cannot sign in at all, and unmanaged members can, but their tokens lose the organization claim, so check the organization’s state before debugging the provider.
What does this look like on Skycloak?
Organizations and identity brokering are standard Keycloak features, so on a realm running Keycloak 26.8 or later you configure them in the admin console without running a separate discovery service. Skycloak runs upstream Keycloak, so the same configuration works on a self-hosted deployment of the same version, which keeps your options open.
Frequently asked questions
What is home realm discovery?
It is the step in a login flow where the system decides which identity provider should authenticate a user, commonly by looking at the domain of their email address, and redirects them without showing a list of providers.
Does Keycloak support home realm discovery?
Yes, through Organizations. Assign an email domain to an organization, link the organization’s identity provider, set the domain’s routing, and turn on auto redirect. Keycloak 26.8 documents this behavior.
What is the difference between kc_idp_hint and Organizations domain routing?
kc_idp_hint is a request parameter that your application sets to name the identity provider directly. Organizations routing lets Keycloak choose the provider from the email the user types. The first suits custom login links and the second suits a single shared login page.
Can one identity provider serve several domains?
Yes. The documentation says the same identity provider can be the routing target for multiple domains, including domains that belong to different organizations, and each organization configures its own domains independently.
Do I need to verify a customer’s domain before adding it?
You should. The 26.8 documentation does not describe an automatic ownership check, and the verified field on a domain is not enforced, so confirm control of the domain yourself before routing logins to a provider based on it.
Is Microsoft’s home realm discovery the same thing?
It solves the same problem. Entra’s policy and domain_hint parameter route sign-ins within Microsoft’s platform, and Keycloak’s Organizations feature gives you comparable routing in your own realm.