Keycloak Realms Explained: Clients, Roles and Tokens

A Keycloak realm is an isolated tenant inside one Keycloak server. It holds its own users, credentials, roles, groups, clients, login flows and signing keys, and it issues tokens from its own URL path, /realms/{realm-name}. A realm authenticates only the users it controls. Every installation starts with a master realm reserved for administration.

Keycloak is an open source identity and access management server, and the realm is its administrative namespace. A client represents one application inside that namespace, so one realm usually holds many clients. Start with the realm boundary, then decide which applications belong inside it and what each application should receive in its tokens.

The design below follows Keycloak’s Server Administration Guide, with deployment and caching details from the official guides listed in Sources. The examples are planning scenarios. Token lifetimes and session limits should follow the requirements of the applications using them.

For related deployment and troubleshooting topics, browse our single-sign-on operations guides.

What Is a Realm in Keycloak?

A realm is the unit Keycloak uses to separate identities. The Server Administration Guide says a realm “manages a set of users, credentials, roles, and groups,” that a user belongs to and logs into a realm, and that realms “are isolated from one another.” Keycloak’s Docker getting-started guide calls a realm “equivalent to a tenant.”

The realm name is also part of every protocol URL. Keycloak’s OIDC endpoint reference lists each endpoint as a path under /realms/{realm-name}, prefixed with the server’s base URL. The realm root is the issuer: the cross-domain chaining guide gives http://localhost:8080/realms/domainb as the issuer for realm domainb.

Realms Are Isolation Boundaries

A realm manages and authenticates its own users. Creating an account in one realm does not automatically create an account in another or establish shared login between them. Identity brokering can deliberately connect identity providers, but that is an integration you configure.

Applications must use the issuer for the intended realm. Two clients with the same client ID in different realms are separate registrations. Treat the realm name and issuer as part of an application’s configuration contract.

Keycloak Realm vs Client: What Is the Difference?

A realm is the security domain: it owns users, login policy, sessions and signing keys. A client is one application registered inside a realm, with its own client ID, redirect URIs, public or confidential type and client roles. One realm usually holds many clients, and a client never spans realms.

One Realm vs Many: Choose the User Boundary First

One realm is a useful starting point when the same people use several applications under a shared account and login policy. For example, a portal, a document service, and a dashboard can be three clients in one realm. Client roles can describe different permissions in those applications without splitting the user directory.

Several realms make sense when populations need independently managed identities and realm policies. Keycloak’s administration guide uses employees and customers as an example of separate populations. The decision is about who owns the accounts, which login rules apply, and which applications those accounts should reach.

This is a planning framework, not an automatic tenant-to-realm rule. Write down the reason for each boundary before creating it. A realm per application multiplies the user, role, and client configuration that operators must maintain. Conversely, forcing unrelated populations into one realm makes the application authorization model carry more of the separation.

Realm isolation also differs from infrastructure isolation. Realms on the same deployment share its process, database service, and operational lifecycle. If a requirement concerns independent outages or infrastructure administration, evaluate separate deployments as well as separate realms. Adding a realm alone does not create dedicated compute or a separate database server.

Organizations: Many Tenants in One Realm

For B2B products serving many customer companies, consider Organizations before creating a realm per customer. The Keycloak 26.0.0 release of October 2024 made the feature fully supported, and the organizations documentation describes it as multi-tenancy within a realm. Members can join several organizations, and organization data can be included in ID and access tokens. Separate realms still fit customers that need different realm-level policy or delegated administration.

The Master Realm: Keep Applications in Their Own Realm

Keycloak creates the master realm for administration. The official guidance reserves it for creating and managing other realms. Create an application realm before registering application clients or onboarding their users.

The practical reason is privilege separation. Administrators in master can receive permissions over other realms; a master administrator with the global admin role can manage every realm. Ordinary application roles should not be mixed with that server administration role model.

Administration does not require giving every operator global access. Each application realm has a dedicated Admin Console, and Keycloak supports realm administration roles with narrower responsibilities. Decide whether an operator needs to manage the server or only a particular realm, then grant the corresponding access.

Before handing an issuer URL to an application team, confirm the selected realm in the console and check its client registration. A successful login to the administration console proves administrator access; it does not establish that the application’s own realm and permissions are ready.

How to Create a Keycloak Realm

Sign in to the Admin Console as a master administrator, or script the job with the Admin CLI. The console steps follow Keycloak’s getting-started guide, which used the quay.io/keycloak/keycloak:26.7.5 image when checked in October 2026:

1. Select Manage realms in the left column, then click Create realm.
2. Enter a realm name such as myrealm. It becomes part of every endpoint URL, so settle it before sharing issuer URLs.
3. Click Create.
4. Under Users, click Create new user, then set a password on the Credentials tab.
5. Sign in as that user at http://localhost:8080/realms/myrealm/account to confirm the realm works.

From a shell, the Admin CLI documentation logs in against master, then creates and lists realms. It notes that Keycloak disables realms by default, hence enabled=true:

kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin
kcadm.sh create realms -s realm=demorealm -s enabled=true
kcadm.sh get realms

Clients, Scopes and Roles

A client represents an application requesting tokens. Confidential clients can hold a secret and are used by server side applications. Public clients cannot keep a secret, which covers browser and mobile applications, and must rely on the authorization code flow with PKCE rather than any flow that returns tokens directly.

Roles come in two forms. Realm roles apply across the realm, and client roles are scoped to a single application. Assign roles to groups rather than individual users so membership changes do not require touching authorization data. Composite roles bundle other roles and are useful, but deep nesting makes effective permissions hard to reason about.

Keep role assignment distinct from token contents. Giving a user a role and choosing whether a client receives that role in a token are separate decisions. Review both when an application reports missing permissions.

Client Scopes and Audience Mapping

A client scope groups protocol mappers and role scope mappings that can be shared by clients. Protocol mappers determine claims in tokens or assertions; role scope mappings constrain which assigned roles are available to the client. Sharing a scope is useful when several applications need the same claim definition.

Default client scopes apply when tokens are issued, regardless of the OIDC request’s scope parameter. Optional client scopes apply when the client requests them through that parameter. The dedicated client scope holds mappings specific to one client. Put shared mappings in a reusable scope and keep application-specific mappings with the application.

Audience mapping answers a different question: which service should accept the access token? The aud claim identifies intended recipients. A token being signed by the right realm is insufficient grounds for every API in that realm to accept it.

Keycloak documents an Audience Resolve mapper that derives audiences from applicable client roles, and a Hardcoded Audience mapper for explicitly adding a configured audience. Choose the mapping that matches the API contract, and configure the API to validate its expected audience as well as the issuer, signature, and expiry.

For a hypothetical portal calling an inventory API, write down the expected API audience before choosing the mapper. Check a token issued to the portal for that audience and for the inventory permissions it needs. Avoid adding every API as an audience just to remove an integration error.

The client’s Client scopes → Evaluate view can show effective mappings and example tokens for a selected user and requested scopes. Compare default-only output with output that includes an optional scope. Check access tokens, ID tokens, and UserInfo separately: their consumers and purposes differ. Keep claims limited to what those consumers need, and avoid assuming token byte size equals cached session size.

Authentication Flows and Federation

Authentication flows are configurable chains of executions covering login, registration, password reset, and step up authentication. Copy a built in flow before editing it, and keep custom flows minimal, since a misconfigured required execution can lock everyone out of a realm.

User federation connects Keycloak to an existing LDAP or Active Directory source. Decide early whether Keycloak imports users into its own database or reads them on demand, and decide whether the directory or Keycloak owns each attribute. Getting mapper direction wrong is a common cause of attributes silently reverting after a sync.

Identity brokering is a different mechanism. It delegates login to another OIDC or SAML provider rather than reading a user store directly.

Sessions, Tokens and Clustering

Keycloak distinguishes a user session from the client sessions beneath it. A user signed into several applications can have one SSO user session and several client sessions. An authentication session holds state while login is still in progress; it is not the same object as an established user session.

Under the defaults described in the current caching guide, established user and client sessions are persisted in the database and loaded into embedded caches on demand. Those two caches default to 10,000 entries per node and one owner per entry. Evicting an entry from a cache therefore differs from ending the underlying session.

Use the deployment’s actual cache configuration when estimating what realm sessions cost in heap. The Keycloak memory and heap sizing calculator models session counts and stated assumptions; it does not calculate login-rate CPU requirements or enforce realm session limits.

Realm-Level Token Lifespans and Session Timeouts

Realm settings separates Tokens from Sessions. Access Token Lifespan controls how long an access token remains valid. SSO Session Idle controls inactivity, while SSO Session Max sets an outer lifetime for the user session. A refresh request can renew the idle timer; it does not remove the maximum lifetime.

Client Session Idle and Client Session Max apply to an application’s client session. The administration guide describes client overrides and inheritance from realm SSO values where a client timeout is left at zero. Review overrides when one application signs users out sooner than another.

Shorter access tokens can reduce the period an already issued token remains usable, while clients maintaining access need to refresh more often. Ending a Keycloak session does not guarantee immediate rejection of an existing JWT by an API that validates it locally. Document logout and token validation behavior together instead of treating a short idle timeout as token revocation.

Offline access needs separate review. Its session rules differ from ordinary SSO, and the maximum lifetime depends on whether Offline Session Max Limited is enabled. Inventory applications that request offline access before changing those settings. There is no universally correct lifetime to copy into every realm.

Concurrent Sessions: Limits Are an Authentication Policy

A session timeout limits duration. The User Session Count Limiter authenticator limits the number of sessions for a user. Keycloak supports a realm-wide per-user limit and a per-client per-user limit, with behavior that either rejects a new session or terminates the oldest one. These are not total realm capacity limits.

Configure the limiter in a copied authentication flow using the administration guide’s placement rules. It needs to run after the user is identified. Browser flows need particular care around the Cookie authenticator, because an existing SSO session should not be treated as a new login.

Include every supported login path in the policy review, including brokered login where applicable. Configuring one browser path does not establish consistent limits for all other flows. Use controlled accounts to check the chosen behavior across separate browser sessions, and document what a user will see when the limit is reached.

Realm Export and Import for Promotion Between Environments

Use a reviewed realm configuration to carry client, role, and flow design between environments. Keycloak supports JSON export and import, but its import/export guide explicitly distinguishes that process from complete backup and recovery. Persisted sessions and user/admin events are among the data an export omits.

For configuration promotion, the CLI export supports --users skip. Skipping users does not make the rest of the export safe to publish: review credentials and other sensitive settings before committing a sanitized configuration. Keep environment-specific secrets outside version control.

All nodes should be stopped for a consistent CLI export. An overriding CLI import requires stopped nodes because the import process does not join the cache cluster. Startup import with --import-realm skips an existing realm, so restarting a server with changed JSON is not a general configuration update mechanism. The Admin Console’s partial export also masks sensitive values and excludes users; it is not a complete clone.

As a promotion checklist, record the intended target realm, client registrations, requested scopes, and flow bindings before the change. Supply the target environment’s callback URLs and credentials through its deployment process. Afterward, verify a representative login, expected token audience, refresh behavior, and logout using that environment’s applications. Retain a database recovery plan separately from the configuration export.

Server hostname and reverse-proxy settings also need their own deployment configuration. A realm export does not capture the entire server installation. Incorrect public URL handling can produce issuer mismatches after promotion; Keycloak hostname and proxy errors covers those options and their symptoms.

Where to Go Next

Three follow-on questions come up almost immediately after the concepts above are settled:

• How much hardware does this need? See Keycloak memory usage and heap sizing, or run the numbers directly in the sizing calculator.
• Why will nothing work behind my proxy? See Keycloak hostname and proxy errors.
• Is Keycloak the right tool at all? See Keycloak vs authentik vs Authelia for a comparison against the two self-hosted alternatives it is most often weighed against.

FAQ

is a keycloak realm the same as a tenant?

Usually, yes. Keycloak’s getting-started guide calls a realm equivalent to a tenant, since each keeps its own users, clients and login policy. For B2B products where many customer companies share the same applications, Organizations, fully supported since Keycloak 26, provide multi-tenancy inside one realm instead of one realm per customer.

can a user log in to more than one keycloak realm?

Not with a single account. Realms are isolated, so an account in one realm does not exist in another, and each realm keeps its own SSO sessions. To reuse one set of credentials, configure identity brokering: register the first realm as an OpenID Connect identity provider in the second, and users can log in through it.

how do i find my keycloak realm’s issuer url?

Take the server’s public base URL and append /realms/ plus the realm name, for example https://sso.example.com/realms/myrealm. Confirm it by opening /realms/myrealm/.well-known/openid-configuration, whose discovery document lists the issuer and every endpoint. If the issuer shows the wrong host or scheme, fix the hostname and proxy settings, not the application.

how many realms can keycloak handle?

It depends on version and cache sizing rather than a fixed limit. In October 2025 a Keycloak maintainer wrote in a GitHub discussion that 26.4 should handle more than 1,000 realms as long as the realm cache keeps growing. That cache defaults to 10,000 entries per the caching guide, resized with --cache-embedded-realms-max-count.