Understanding Keycloak Realms: Isolation, Management, and Best Practices

Realm

In Keycloak, a Realm (translated as “领域”) is used to logically isolate a set of resources, similar to a multi‑tenant environment. Different Realms are completely isolated from each other and have independent configurations.

When to Use a Realm

Realms are useful when you need to separate a specific group of users or manage resources for a set of services in a unified way.

For example, if you deploy an application at felord.cn, you can create a Realm named felord.cn to manage its roles, resources, and clients, while the client focuses on business logic. Keycloak acts as a centralized platform that manages the lifecycle of Realms, which can interoperate via the OIDC protocol.

Master Realm

The built‑in Master Realm functions like a root user in Linux. Its administrator can view and manage any other Realm created on the Keycloak server. The Master Realm itself is also a client, following the naming pattern <realm name>-realm.

admin : Super‑admin with full access to all Realms.

create‑realm : Allows creation and full management of a new Realm.

Recommendation: Use the Master Realm only for managing other Realms and not for business operations.

Other Realms

Other Realms are created by the Master Realm administrator. Creation is straightforward and the default configuration is usually sufficient.

Setting Up a Realm Management Account

For the previously created Realm felord.cn, there are two ways to create an independent admin account.

Using a Master User

Create a user in the Master Realm, remove the admin and create‑realm roles, and assign the client role felord.cn‑realm to the user. This grants the user full management rights over the felord.cn Realm. Access the console via:

http://<serverurl>/auth/admin/master/console/#/realms/{realm-name}

Using a Realm‑Specific Client User

Create a user inside the felord.cn Realm and assign all client roles from realm‑management to this user. This user can manage only the felord.cn Realm via:

http://<serverurl>/auth/admin/{realm-name}/console

A user can belong to only one Realm.

Extension

The Keycloak Admin Client is an API‑based tool for managing Realms programmatically. See the previous article for an introduction.