Keycloak Realm Isolation: How to Decide When to Create a New Realm

The Realm Boundary: When to Split

Creating a new Keycloak realm is an architectural boundary decision, not a convenience feature. A realm is the top-level security domain that isolates users, credentials, roles, and identity providers—external login systems such as corporate directories or social accounts. The useful takeaway: create a separate realm when you need a distinct trust boundary, such as separate organizations, different identity provider requirements, or independent user lifecycles, rather than merely to group applications.

How Realm Isolation Works

Keycloak stores every realm in its database. When a user authenticates, the realm identifier becomes the token issuer, and all clients, roles, and required actions are resolved inside that realm. This means a user in one realm cannot access a client in another realm unless an identity provider or user federation bridges them. Because the boundary is enforced at the realm level, misconfiguring a realm’s client secrets or authentication flows affects only that realm’s applications and users.

Creating and Verifying a Realm with kcadm.sh

To create a realm, use the Admin CLI (kcadm.sh) on a machine that can reach the Keycloak server and has admin credentials. The command below creates a realm named partner-portal and enables it:

kcadm.sh create realms -s realm=partner-portal -s enabled=true \
  --server http://localhost:8080 --realm master --user admin

Run this from the Keycloak bin directory or any host with kcadm.sh installed and network access to the Admin REST endpoints. You need realm-admin or master-realm admin privileges. Replace partner-portal with your desired realm name, and adjust --server and credentials to match your deployment. If your environment uses a configuration file or truststore for TLS, those settings may already be picked up automatically.

After creation, verify the realm exists and is enabled:

kcadm.sh get realms/partner-portal \
  --server http://localhost:8080 --realm master --user admin

Confirm that the returned JSON shows "enabled" : true and the realm name you specified. You can also log in to the Admin Console, select the realm from the dropdown, and check that Realm Settings reflects the expected state.

Practical Limits on Realm Count and Size

Keycloak handles dozens of realms comfortably. As a practical guideline, performance tends to degrade beyond roughly 100 realms on a single server, though the exact number depends on hardware and database capacity. Each realm also consumes memory for its user sessions and metadata; a single realm can practically support millions of users, but pushing past 2–3 million users increases database connection pressure and login latency. These are practical ceilings, not hard limits, and should be validated against your own load tests before committing to a large multi-realm deployment.

Common Mistakes and How to Avoid Them

• Assuming client IDs are globally unique. Client IDs are unique only within a realm. The same client ID can exist in multiple realms, which is useful for multi-tenant applications, but if your application omits the realm in its authorization request, tokens may be issued from the wrong realm. Always include the realm in the OpenID Connect discovery URL and token requests.
• Leaving enabled false or forgetting required actions. A realm created with enabled=false is inactive and will reject authentication. Similarly, disabling required actions (such as password update or OTP setup) per realm can weaken security defaults. Review realm settings immediately after creation.
• Applying global settings without checking inheritance. Some server-level settings can influence realm behavior. Changing a global default without verifying how realms inherit it may unintentionally alter other realms. Test configuration changes in a non-production realm first.

Removing a Test Realm

If you created the realm for testing and need to remove it, deletion is permanent and destroys all users, clients, and roles inside it:

kcadm.sh delete realms/partner-portal \
  --server http://localhost:8080 --realm master --user admin

Run the same command with the correct realm name to clean up. There is no soft delete; export any data you need before running this.

Verification Checklist

Beyond the CLI check, log in to the Admin Console, select the realm from the dropdown, and confirm that Realm Settings shows the expected display name, enabled status, and client list. If the realm does not appear, re-run the get command and check server logs for database or permission errors.