What Is a Realm in Keycloak?
Realms are the single most important concept to understand before touching anything else in Keycloak. This guide explains what they are, why they exist, and how they quietly shape every login flow your applications will ever use.
Imagine a large office building shared by several completely unrelated companies. Each company has its own reception desk, its own employee badges, its own visitor policy, and its own security rules — even though they’re all physically inside the same building. One company’s badge would never open another company’s floor. Keycloak’s concept of a realm works exactly like this: it’s a self-contained “company floor” for managing identity, completely walled off from every other realm inside the same Keycloak installation. This guide unpacks that idea piece by piece, starting from zero assumptions about Keycloak or identity management.
1What Is a Realm?
The foundation every other Keycloak concept sits on top of.
Keycloak is an open-source identity and access management system — software whose entire job is to handle logins, user accounts, and permissions so individual applications don’t have to build that machinery themselves. Within Keycloak, a realm is a completely isolated space that manages its own set of users, its own applications, its own login rules, and its own security settings, independent of every other realm running on the same server.
Think of a realm like a separate country with its own passport office. A passport issued by Country A means nothing to Country B’s border control — each country manages its own citizens, its own passport rules, and its own security checks, even though both countries might exist on the same continent. Two realms on the same Keycloak server are just as separate: a user account in one realm simply does not exist, in any sense, inside another realm.
This isolation is not a minor detail — it’s the entire reason realms exist. A single Keycloak installation can safely host many different products, teams, or even entirely different companies at once, because each one lives inside its own realm and cannot see or affect the others.
Users
Every person who can log in belongs to exactly one realm’s user directory.
Clients
The applications registered to use that realm for login, each with their own settings.
Roles & Groups
The permission labels and user groupings defined specifically for that realm.
Security Policies
Password rules, session lifetimes, and login flows configured independently per realm.
A realm is the outermost administrative boundary in Keycloak. Everything else you’ll ever configure — users, applications, permissions — is defined inside a specific realm and stays there.
2Realm vs. Client vs. User vs. Master Realm
Keycloak has several terms that sound related but describe very different layers.
Newcomers to Keycloak often confuse a handful of terms that actually describe a clear hierarchy. Getting this straight early saves enormous confusion later.
Picture that same office building again. The realm is the entire company floor. A client is one specific door on that floor — say, the accounting department’s entrance — that has its own access rules. A user is an individual employee who has been issued a badge. And the master realm is the building’s own security control room — it doesn’t belong to any tenant company, and it exists purely to manage the building’s security system itself, including creating and administering every other floor.
| Term | What It Is | Analogy |
|---|---|---|
| Realm | An isolated space managing its own users, apps, and rules | An entire company floor in a shared building |
| Client | A single application registered to authenticate through a realm | One specific department’s entrance door |
| User | An individual account that can log in within one realm | An employee holding a badge for that floor |
| Master Realm | Keycloak’s own built-in realm for administering the whole server | The building’s central security control room |
The master realm is special and is created automatically when Keycloak is first installed. It’s meant only for administrators who manage Keycloak itself — not for storing the regular end-users of your applications. Mixing everyday application users into the master realm is one of the most common beginner mistakes, covered further in Chapter 9.
3The Building Blocks Inside a Realm
A realm is a container — here’s everything it typically holds.
When you create a new realm, it starts out mostly empty, like a freshly built office floor waiting for furniture. Over time, a realm accumulates several kinds of configuration, each serving a distinct purpose.
User Federation
Connections to external user stores — such as a company directory — so existing accounts don’t need to be recreated manually.
Identity Providers
Links to outside login sources, like “Sign in with Google,” configured separately for each realm.
Roles and Groups
Labels defining what a user can do, and collections of users who share the same permissions.
Authentication Flows
The exact sequence of steps a login must go through — password check, MFA prompt, terms acceptance, and so on.
Clients
The applications registered to use this realm for authentication, each with its own redirect rules and token settings.
Realm Settings
Global rules for this realm alone — password policy, session timeouts, token lifespans, and branding.
If a realm is a company floor, then roles and groups are the different job titles and departments, authentication flows are the security checkpoint procedures at the entrance, and identity providers are the visitor badges the reception desk is willing to honor from partner companies.
None of these components are shared automatically between realms. A role called “admin” defined in one realm has absolutely no relationship to a role of the same name defined in a different realm — they are entirely separate objects that happen to share a label.
4How a Realm Works Internally
What actually happens when a user logs in through a specific realm.
Every login request sent to Keycloak must specify which realm it belongs to — there’s no such thing as a “realm-less” login. This is usually baked directly into the web address an application sends users to, so the correct realm is always known before any credentials are even checked.
Application Redirects to a Specific Realm’s Login Page
The client application sends the user to Keycloak’s login screen, which is always tied to one particular realm by its web address.
Keycloak Loads That Realm’s Configuration
Keycloak looks up the settings, authentication flow, and branding belonging only to that realm — nothing from any other realm is considered.
The User Authenticates Against That Realm’s User Directory
Credentials are checked only against accounts that exist inside this specific realm.
A Token Is Issued, Scoped to That Realm
The resulting access token is stamped with the realm’s identity — it will only be accepted by applications registered as clients within that same realm.
sequenceDiagram
participant U as User
participant App as Application (Client)
participant K as Keycloak
participant R as Realm's User Store
App->>K: Redirect user to /realms/{realm-name}/login
K->>K: Load configuration for that realm only
U->>K: Submit credentials
K->>R: Verify against this realm's users
R-->>K: Match confirmed
K-->>App: Issue token scoped to this realm
Because every part of the flow — configuration, users, and the final token — is scoped to one realm, a token issued by Realm A is structurally meaningless to an application registered under Realm B, even if both realms live on the exact same Keycloak server.
5Common Ways Teams Organize Realms
There’s no single “correct” number of realms — different situations call for different structures.
Master Realm
Keycloak’s built-in administrative realm, reserved for managing the server itself — never for application end-users.
Single Application Realm
One realm dedicated to a single product, holding all its users, clients, and roles in one place.
Per-Environment Realms
Separate realms for development, staging, and production, keeping test accounts completely isolated from real customer data.
Per-Tenant Realms
One dedicated realm per customer organization, giving each tenant a fully independent identity space with its own branding and policies.
Per-Environment Realms in Practice
A development team might run a “myapp-dev” realm full of throwaway test accounts, a “myapp-staging” realm mirroring production settings for final testing, and a “myapp-prod” realm holding actual customer accounts — ensuring a mistake made while testing never touches real users.
Per-Tenant Realms for B2B Software
A company selling software to other businesses might create one realm per customer, so that Customer A’s employees, login page branding, and password policy are entirely separate from Customer B’s — even though both run on the same underlying Keycloak deployment.
6Realm Isolation: What Stays In, What Crosses Over
Understanding exactly where the walls between realms are — and the rare cases where they can be deliberately crossed.
| Item | Isolated Per Realm? |
|---|---|
| Users and their credentials | Yes — always fully isolated |
| Roles and groups | Yes — a role in one realm is unrelated to a same-named role elsewhere |
| Clients (registered applications) | Yes — a client is registered under exactly one realm |
| Authentication flows and policies | Yes — each realm defines its own independently |
| Identity brokering (linking realms deliberately) | Possible, but only when explicitly configured |
That last row matters: realms are isolated by default, but Keycloak does allow deliberate, explicit connections between them — most commonly through a feature called identity brokering, where one realm is configured to trust logins coming from another realm, similar to how a website can trust “Sign in with Google.”
flowchart TD
subgraph RealmA[Realm: Customer A]
UA[Users A] --> CA[Clients A]
end
subgraph RealmB[Realm: Customer B]
UB[Users B] --> CB[Clients B]
end
subgraph Master[Master Realm]
Admin[Keycloak Administrators]
end
Admin -.manages.-> RealmA
Admin -.manages.-> RealmB
RealmA -. no direct connection .- RealmB
Isolation happens by default, not by accident. Nothing automatically leaks between realms — any connection between two realms has to be deliberately configured by an administrator, which is precisely what makes realms a trustworthy security boundary.
7Multi-Realm Architecture and Multi-Tenancy
Why realms are the tool of choice for building software that serves many separate customers.
Software that serves multiple independent customer organizations from one shared system is called multi-tenant software. Realms map naturally onto this need, because each tenant can be given its own realm — its own users, its own branding, its own security rules — without the engineering team having to build tenant isolation from scratch.
It’s the difference between one shared filing cabinet where everyone’s paperwork is mixed together with color-coded labels (fragile, error-prone), versus giving each department its own locked filing cabinet entirely (naturally isolated, much harder to mix up by accident). A dedicated realm per tenant is the “own locked cabinet” approach.
The Trade-Off: One Big Realm vs. Many Small Realms
Multi-tenancy can also be handled inside a single realm, using groups and roles to separate tenants logically instead of physically. Both approaches are valid, and the right choice depends heavily on how strict the isolation requirement is and how many tenants are involved — explored further in Chapter 11.
When Per-Tenant Realms Shine
Regulated industries, or customers who demand their data never technically touch another customer’s configuration, benefit enormously from the hard boundary a dedicated realm provides.
When a Shared Realm Makes More Sense
Consumer applications with thousands or millions of individual tenants (rather than a handful of large business customers) often find managing that many separate realms impractical, and instead separate tenants using groups within one realm.
8Security Considerations Within Realms
Realm boundaries are powerful, but only if configured with care.
Overusing the Master Realm
Storing application end-users in the master realm exposes them to the same administrative surface used to manage all of Keycloak itself.
Overly Broad Identity Brokering
Trusting logins from another realm without carefully scoping what that trust grants can quietly widen who can access sensitive applications.
Weak Realm-Level Policies
Password policy, session timeout, and brute-force protection are all configured per realm — leaving defaults unreviewed in a high-stakes realm is a common gap.
Excessive Admin Permissions
Granting broad administrative rights over many realms to more people than necessary increases the damage a single compromised admin account could cause.
Each realm can enable its own brute-force detection, password complexity rules, and session expiry — reviewing and tightening these per realm, rather than accepting defaults everywhere, is one of the simplest high-value security steps available.
9Design Patterns and Anti-Patterns
Hard-won lessons from teams who’ve operated Keycloak in production.
Problem
Creating application end-users inside the built-in master realm instead of a dedicated realm.
Why It’s Harmful
The master realm is specifically meant for Keycloak server administrators. Mixing ordinary application users into it blurs the line between “people who can log into an app” and “people who can reconfigure the entire identity server,” creating unnecessary risk.
Correct Approach
Always create a separate, purpose-built realm for each application or tenant, and leave the master realm exclusively for Keycloak administration.
Problem
Creating a brand-new realm for every minor variation instead of thinking through a clear realm strategy up front.
Why It’s Harmful
Realm sprawl makes configuration changes tedious to replicate consistently, multiplies the number of places security settings must be reviewed, and makes the overall system harder to reason about.
Correct Approach
Decide a clear, intentional realm strategy — by environment, by tenant, or by product — before realms start accumulating, and use groups or roles within a realm for finer-grained separation instead of creating new realms casually.
Design Pattern: Environment-Isolated Realms
Keeping development, staging, and production entirely separate at the realm level prevents test data, misconfigurations, or experimental authentication flows from ever touching real user accounts.
Design Pattern: Realm as the Multi-Tenancy Boundary
For B2B products with a manageable number of large customers, giving each tenant its own realm turns tenant isolation into a built-in platform guarantee rather than something the application team must carefully re-implement themselves.
10Best Practices and Common Mistakes
Practical guidance for anyone setting up or maintaining realms.
Reserve the Master Realm for Administration Only
Never store regular application users there — create a dedicated realm instead.
Decide a Realm Strategy Before You Start
Agree up front whether realms will be split by environment, by tenant, or by product, so growth stays organized.
Review Each Realm’s Security Settings Individually
Password policy, session timeouts, and brute-force protection don’t inherit sensible defaults automatically across realms — check each one.
Limit Who Has Administrative Rights Across Multiple Realms
Grant the narrowest administrative scope that still lets each team do their job.
Common missteps include forgetting that roles and groups don’t carry over between realms, assuming a token from one realm will work against another realm’s client, and leaving unused test realms active in production long after they’ve served their purpose.
11Advantages and Disadvantages: One Realm vs. Many Realms
The central architectural trade-off every Keycloak deployment eventually has to weigh.
Single Shared Realm (Separating Tenants With Groups/Roles)
Advantages
- Simpler to operate — one set of realm-level settings to maintain
- Scales more easily to a very large number of tenants
- Easier to share certain resources or reporting across all users
Disadvantages / Trade-offs
- Isolation depends entirely on correct application logic, not a platform guarantee
- A configuration mistake has a larger potential blast radius
- Harder to give each tenant fully custom branding or security policy
Dedicated Realm Per Tenant
Advantages
- Strong, built-in isolation between tenants
- Each tenant can have fully independent policies and branding
- Easier to delete or suspend one tenant cleanly, without affecting others
Disadvantages / Trade-offs
- More realms to configure, monitor, and keep consistent over time
- Can become unwieldy with a very large number of tenants
- Cross-tenant features (like shared reporting) require extra engineering effort
12Monitoring and Auditing Across Realms
Visibility into what’s happening inside — and across — realms is essential once more than one exists.
Per-Realm Event Logging
Keycloak can log login successes, failures, and admin actions separately for each realm, making it possible to audit one tenant without wading through another’s activity.
Admin Action Auditing
Tracking who changed realm settings, created clients, or modified roles is critical, since these changes can quietly reshape an entire tenant’s security posture.
Cross-Realm Dashboards
Teams running many realms often build a consolidated view pulling metrics from each realm’s logs, since Keycloak itself treats each realm’s data separately by design.
13Real-World and Industry Examples
Seeing how organizations actually use realms in production.
SaaS Platforms Serving Enterprise Customers
A business software vendor selling to large enterprises often provisions one realm per customer, letting each enterprise enforce its own password policy or connect its own corporate identity provider without affecting other customers.
Internal Company Tooling
An organization might run one realm for employee-facing internal tools (integrated with their corporate directory) and a completely separate realm for customer-facing products, keeping staff and customer identities entirely apart.
Environment Separation in DevOps Pipelines
Engineering teams commonly maintain distinct development, staging, and production realms so authentication changes can be tested safely before ever touching real user accounts.
Government and Regulated Sector Deployments
Organizations with strict compliance requirements frequently rely on realm-level isolation to demonstrate that one department’s or agency’s user data is architecturally separated from another’s, not just logically separated by application code.
14Frequently Asked Questions
Yes — a single Keycloak installation can host as many realms as needed, and this is in fact one of its core design purposes, allowing one deployment to serve many separate applications or tenants.
A realm is the broader isolated space that manages users and policies; a client is one specific application registered inside a realm to use it for login. A single realm commonly has many clients registered under it.
No — the master realm is reserved for Keycloak’s own administrators. Application end-users should always live in a separate, dedicated realm created specifically for that purpose.
Not by default — realms are isolated from each other. It’s only possible if an administrator deliberately sets up identity brokering to make one realm trust logins coming from another.
No. Roles, groups, and every other configuration item are defined independently within each realm. A role with the same name in two different realms is really two unrelated objects that simply happen to share a label.
There’s no universal answer — it depends on isolation requirements, the number of tenants or environments involved, and operational complexity a team is comfortable managing. Many projects start with just a few realms split by environment, then add more as multi-tenancy needs grow.
15Summary and Key Takeaways
A realm is Keycloak’s fundamental isolation boundary — a self-contained space holding its own users, clients, roles, and security policies, completely separate from every other realm on the same server unless a connection is deliberately configured. Understanding realms first makes every other Keycloak concept — clients, roles, identity brokering, multi-tenancy — click into place, because all of them exist inside, and are shaped by, the realm that contains them.
Key Takeaways
- A realm is a fully isolated identity space — its users, clients, roles, and policies never automatically cross into another realm.
- The master realm is for Keycloak administration only — application end-users always belong in a separate, purpose-built realm.
- Every login and token is scoped to exactly one realm, from the initial redirect through to the final issued token.
- Realms are a natural fit for multi-tenancy, giving each tenant a hard, platform-enforced boundary rather than relying purely on application logic.
- Isolation is the default, and crossing it is deliberate — features like identity brokering only connect realms when an administrator explicitly configures them to.
- A clear realm strategy prevents sprawl — deciding up front whether to split by environment, tenant, or product keeps a growing deployment manageable.
- The single-realm vs. many-realms decision is a genuine trade-off between operational simplicity and the strength of tenant isolation.