Realms

What is a realm?

A realm is the top-level container in Keycloak. Every object in Keycloak — users, clients, roles, identity providers, token policies — belongs to exactly one realm. Realms are completely isolated from each other: a user in realm shop cannot log in to an application registered in realm blog, and their sessions are never shared.

You can think of a realm as a tenant in a multi-tenant SaaS system, except that each realm is managed entirely within one Keycloak server.

The master realm

Keycloak is installed with one realm already in place: master. The master realm has a special purpose: it is the administrative realm. When you open the Keycloak admin console and log in, you are authenticating against master.

The master realm can create and manage other realms, but it should never be used to register your own applications or store your application’s users. Mixing your app users with the administrative super-users of master is a serious security risk.

Creating a realm

1. Open the Keycloak admin console at http://localhost:8080 and sign in with your admin credentials.
2. In the top-left corner, click the realm name drop-down (it initially shows Keycloak or master).
3. Click Create realm.
4. In the Realm name field, enter a short, lowercase, hyphen-separated name for your realm (e.g., my-app).
5. Make sure Enabled is toggled on.
6. Click Create.

Keycloak creates the realm and switches your console context into it. All subsequent configuration (clients, roles, users) will belong to this new realm.

Organizations: multi-tenancy without realm sprawl

The obvious way to serve many customers is one realm per customer. It works, but it scales badly: every realm needs its own clients, roles, mappers, and themes, and a user who belongs to two customers becomes two accounts.

Keycloak 26 added Organizations as a first-class answer. An organization is a group of users inside a realm, so all of them share the realm’s clients and roles while still being separated by tenant. The organization:v1 feature is supported and on by default; you switch it on per realm from Realm settings → General → Organizations.

What an organization gives you:

• Members — existing realm users you add, or people you invite by email. Members can be managed by the organization or federated in from elsewhere.
• A linked identity provider — a tenant can bring its own IdP, so their staff sign in with their own corporate login while everyone else uses yours.
• Domain matching — map an email domain to an organization and new users land in the right tenant automatically.

Choose between the two models like this:

	Realm per tenant	Organizations
Isolation	Total: separate users, clients, roles, keys	Shared realm, members separated by organization
Config duplication	Every client and role repeated per tenant	Configure clients and roles once
A user in two tenants	Two separate accounts	One account, two memberships
Per-tenant login provider	Yes	Yes, via a linked IdP
Good for	Hard regulatory or data separation	SaaS with many customers on one product

A tour of realm settings

After creating a realm, click Realm settings in the left sidebar. The settings are organised into tabs:

General

• Display name — a human-readable name shown on the login page.
• Frontend URL — override the URL Keycloak uses to build redirect links (useful behind a reverse proxy).
• HTML display name — supports HTML for branded login pages.

Login

• User registration — allow self-service sign-up.
• Forgot password — enable the password reset flow (requires email configured).
• Remember me — let users stay logged in across browser restarts.
• Verify email — require users to confirm their email address after registration.
• Login with email — allow users to enter their email address instead of a username.

Email

Configure the SMTP server Keycloak uses to send verification and password-reset emails. Required if you enable any email-triggered flows.

Tokens

Key settings that control token lifetimes and behaviour:

Setting	Default	What it controls
Access token lifespan	5 min	How long an access token is valid
SSO session idle	30 min	Session expires if idle for this long
SSO session max	10 hours	Hard limit on session length
Refresh token lifespan	Matches SSO session	How long a refresh token can be used

Shorter access-token lifespans reduce the window of exposure if a token is stolen, at the cost of more frequent refreshes.

Keys

Keycloak automatically generates cryptographic keys for signing tokens. The Keys tab shows the active key providers. For production, you should rotate keys periodically. The RS256 provider is the default and produces JWTs signed with an RSA private key; clients verify signatures using the public key available at the realm’s JWKS endpoint:

http://localhost:8080/realms/{realm-name}/protocol/openid-connect/certs

🔐 Never build apps in master

Never register your applications or store application users in the master realm. The master realm is reserved for Keycloak administration. Create a dedicated realm for every project or product.

Trade-offs

Option	Benefit	Cost
One realm per app (realm-per-app)	Completely separates each app’s users, sessions, and token policy, limiting the blast radius if one app has a security issue	You must maintain multiple realms — theme, SMTP, and identity provider settings must be repeated per realm, adding operational overhead
Shared realm (several apps in one realm)	Simpler to set up and maintain; one user can access several apps via SSO immediately	Weaker isolation — a misconfiguration or role mistake in one app can affect another app in the same scope

Common mistakes

• Registering real applications in the master realm — master should be reserved for administering Keycloak itself. Create a separate realm for every project or product so application users aren’t mixed in with super-user administration.
• Forgetting to set token lifespans appropriate to each app’s risk — using the same defaults for every realm, even though some realms (e.g. banking) should have a shorter access-token lifespan than a lower-risk realm.
• Not rotating the signing key periodically in production — leaving the same key in use for the system’s whole lifetime increases risk if the private key ever leaks unnoticed.

Real-world example

A multi-tenant SaaS platform — many SaaS platforms use a realm-per-customer pattern, creating a separate realm for each customer so their users, roles, and sessions are completely isolated from each other, while supporting custom branding and a per-tenant identity provider.

A large organisation with multiple teams — a company running both internal tools and a customer-facing product commonly separates realms by user population, e.g. a staff realm for employees and a customers realm for customers, so password or MFA policy on one side never affects the other.

You run a SaaS product for many customers who all use the same clients and roles. Which model does Keycloak 26 recommend?

One realm per customer, so each is fully isolated Organizations inside one realm, so clients and roles are configured once One realm with a group per customer and no other structure A separate Keycloak server per customer

What is the purpose of the master realm in Keycloak?

It stores the users for your main application It is a reserved administrative realm used to manage Keycloak itself It is the only realm that supports OIDC It is the default realm for all new clients

Which token setting should you shorten to reduce the exposure window if an access token is stolen?

SSO session max Refresh token lifespan Access token lifespan SSO session idle

Where in the admin console do you start the process of creating a new realm?

Clients → Create client The realm name drop-down in the top-left corner → Create realm Realm settings → General → New Users → Add realm

What URL path exposes a realm's public signing keys for token verification?

/realms/{realm}/protocol/openid-connect/token /realms/{realm}/protocol/openid-connect/certs /realms/{realm}/keys/active /admin/realms/{realm}/keys

Submit

Mark as complete