Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: Designing a Multi-Tenant Setup

Choose between one realm per tenant, a shared realm with groups, or Keycloak Organizations. A design project with a decision scorer, naming rules and per-tenant login routing.

You are building a B2B product where many customer companies ("tenants") sign in: each has its own users, some bring their own identity provider, and none may see another's data. How should Keycloak represent tenants? There is no single right answer. This project walks you through the options, trade-offs, and a design you can defend, plus small runnable tools to decide and to route logins.

Keycloak cannot run on this site. The scorer and router below are JavaScript stand-ins encoding rules of thumb from this lesson, not official guidance. The Organizations feature is newer than realms: check your Keycloak version's documentation for what it supports before relying on it.

The three models

1. One realm per tenant

Each customer gets a separate realm. Users, clients, roles, identity providers, themes, and password policies are fully isolated.

  • Strong isolation: separate keys, separate admin boundaries, separate iss per tenant.
  • Per-tenant branding, login policies, and IdPs are trivial.
  • Costs: every realm adds configuration, memory, and startup cost; hundreds of realms slow the admin console and migrations; clients must be created in every realm; token issuers differ so APIs must trust many issuers.
  • Fits: tens to a few hundred tenants with strict isolation needs (regulated customers, white-label).

2. One realm, tenants as groups or attributes

All tenants share the realm. A user belongs to a tenant group (/acme, /globex) or carries a tenant attribute that a mapper puts in the token.

  • Cheap to run; one set of clients and one issuer; scales to many thousands of tenants.
  • Weaker isolation: one admin sees all; a misconfigured mapper or role leaks across tenants; per-tenant IdPs and branding need extra work.
  • You must enforce tenant boundaries in your API using the tenant claim, always.
  • Fits: many small tenants with the same product and no custom IdPs.

3. One realm with Organizations

Recent Keycloak versions add Organizations: inside a realm, an organization groups members, can own email domains, and can be linked to identity providers. Users can be members of several organizations. A token can carry the organization claim through a client scope so your API knows which tenant the user is acting in.

  • Gives per-tenant IdP routing by email domain without a custom flow.
  • Keeps one issuer and one set of clients.
  • Isolation is still logical, not physical: the realm admin sees everything.
  • Fits: SaaS with many tenants, some with SSO, where a single realm is acceptable.
flowchart LR
  subgraph R1["Model 1: realm per tenant"]
    A1["realm: acme"]
    A2["realm: globex"]
  end
  subgraph R2["Model 2: one realm, groups"]
    B["realm: app<br/>groups /acme /globex"]
  end
  subgraph R3["Model 3: organizations"]
    C["realm: app<br/>orgs acme, globex<br/>domain and IdP per org"]
  end

Isolation decreases from left to right; operational cost decreases too.

A decision scorer

Answer the questions for your product and see which model scores best. Edit the answers and the weights to see how the recommendation changes.

JS Stand-in: tenant model scorer

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Naming and structure

Whatever you choose, decide conventions early, because renaming a realm or alias later breaks redirect URIs and stored data.

  • Realm names: lowercase, stable, URL-safe: acme, never Acme Corp (EU). The name is in every issuer URL.
  • Client IDs: the same across tenants if realms are per tenant (web, api) so code needs no per-tenant constants.
  • IdP aliases: include the tenant: acme-entra. Aliases appear in redirect URIs.
  • Roles: define tenant-independent roles (invoice-editor) and tenant membership separately; avoid roles like acme-invoice-editor, which cause role explosion.
  • Tenant claim: one claim name for every token (tenant or org), set by a mapper from a trusted source, not from a user-editable attribute (see user profile permissions).

Routing a login to the right tenant

Users type an email, and your login experience should send enterprise users to their company IdP. Keycloak's browser flow can be customized for this (via organizations or a custom step), and your app can help with the kc_idp_hint parameter from the brokering lesson. This stand-in shows the routing logic:

JS Stand-in: route an email to a tenant IdP

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Important detail: never let a user choose their tenant by typing a domain they do not own. Domain ownership must be verified (DNS TXT or email verification) before a domain is attached to an organization or IdP, otherwise anyone can claim ceo-company.example and capture its logins.

Isolation checklist in your API

Choose any model, then test these:

  1. Every query includes the tenant from the verified token, never from a request parameter.
  2. A user in tenant A requesting tenant B's resource gets 404 or 403.
  3. Background jobs and caches are keyed by tenant.
  4. Admin APIs are scoped: tenant admins can manage only their users (Keycloak fine-grained admin permissions or your own service in front of the Admin API).
  5. Logs and metrics include the tenant ID but no secrets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which model gives the strongest isolation between tenants?

    Separate realms have separate users, keys, and configuration.
  2. 2. What is the main scaling concern of one realm per tenant?

    Each realm adds overhead, and every client and policy must be managed per realm.
  3. 3. Where should the tenant claim come from?

    If users can edit the source of the claim, they can move themselves into another tenant.
  4. 4. Why verify domain ownership before attaching a domain to a tenant IdP?

    Domain-based routing is only safe when the tenant truly controls that domain.

Summary

  • Realm per tenant isolates strongly but does not scale to thousands of tenants.
  • Shared realm with groups scales but pushes isolation into your API.
  • Organizations add per-tenant domains and IdP routing inside one realm.
  • Use stable names, tenant-independent roles, and a trusted tenant claim.
  • Verify domain ownership and always check the tenant in your API.

Next: Security Hardening Audit