Multi-tenancy with Keycloak: what belongs in the token and what doesn't

Multi-tenancy is usually bought as a login topic and paid for as an architecture topic. The login is configured in two days. The question of who may do what in which context stays with a product for years.

One realm or many?

The first decision is also the most expensive one to revise.

One realm for all tenants is right in most SaaS cases. Tenants become groups or organisations inside the realm, and membership ends up as a claim in the token. Upside: one set of clients, one login flow, one set of templates, central maintenance. Downside: isolation is modelling work, not infrastructure.

One realm per tenant is right when tenants bring their own identity providers, need different password or MFA policies, or must be separated for regulatory reasons. The price: every change has to be rolled out across all realms. From roughly twenty tenants on you need automation, otherwise operations turn into manual labour.

The middle ground that holds up in practice: one realm as the default, plus dedicated realms for large customers with their own IdP.

What belongs in the token

A token is a cache with an expiry date, not a database. The rule of thumb:

• In the token: identity, tenant membership, coarse roles that rarely change. Everything every single request needs.
• Not in the token: fine-grained object permissions, record-level sharing, anything that changes hourly. Those checks belong in the application or a policy engine.

The most common mistake is the opposite: all permissions get packed into the token, the token grows, header limits break, and a revoked permission only takes effect after the next refresh. Permissions that must take effect immediately cannot live in the token.

Cutting roles properly

Three levels are almost always enough:

1. Platform roles — cross-tenant, e.g. support or operations. Few people, strictly audited.
2. Tenant roles — admin, member, guest within an organisation. This is the level customers should manage themselves.
3. Domain permissions — derived from roles, checked in the application against the concrete record.

When role names start containing customer names, the model has tipped over. At that point you are no longer modelling, you are administering.

Self-service instead of back office

Multi-tenancy only pays off once onboarding a new customer stops being a ticket. That includes: create organisation, invite admin, verify domain, manage users, assign roles — done by the customer. Keycloak provides the building blocks but no finished UI. That admin UI is part of the product, not an afterthought.

Migration without a big bang

Existing users are rarely moved over in a single weekend. What works:

• Introduce Keycloak as the leading system and connect the legacy store temporarily via user storage or import-on-first-login.
• Migrate password hashes when the format is compatible — otherwise use a reset flow with clear communication.
• Switch applications one at a time, not all at once. Each switch is its own reversible change.
• Only decommission the legacy system after the last application has moved.

What operations means

An access system is critical infrastructure. That means monitoring on login error rates and token issuance, a documented rotation path for client secrets and signing keys, tested backups of realm configuration as code, and a recovery runbook someone on the team has actually rehearsed.

Short version

Choose the realm strategy deliberately, keep tokens small, cut roles on three levels, build self-service as part of the product and migrate incrementally. Clarifying these five points before the first line of code saves you the edge cases that otherwise land in every application separately.

How we deliver tenancy in a clearly scoped package is described under Keycloak multi-tenancy; the wider frame is our software engineering and delivery work.

Tenant isolation is where security questionnaires and audit questions most often get stuck. What is actually required is described under NIS2 and your software; where your system stands today is what the provability check shows.