What Is a Realm in Keycloak? What Lives Inside One

If you typed “what is realm in keycloak”, the short answer: a realm is an isolated tenant inside one Keycloak server, with its own users, groups, roles, clients, login flows, email settings and signing keys, served under its own URL path, /realms/{name}. Every server ships with a master realm for administration. Your apps belong in a realm you create.

For a homelab, the right count is almost always one application realm, with master left alone. That choice takes ten seconds on day one and an evening to undo later, because the realm name ends up in the OIDC settings of every app you connect. Nobody enjoys redoing it: the cleanup is all copy-paste and no learning.

What does a Keycloak realm actually contain?

A realm contains everything Keycloak needs to log a person into an app: the user directory and credentials, groups and roles, a client registration per app, login flows, identity providers and its own signing keys. The Server Administration Guide says a realm “manages a set of users, credentials, roles, and groups,” and that realms “are isolated from one another and can only manage and authenticate the users that they control.”

In the Admin Console, it splits between the left-hand menu and the tabs under Realm settings:

Three of those rows cause most of the “why doesn’t this work” moments.

Keys are per realm. The key management docs say that “When a realm is created, a key pair and a self-signed certificate is automatically generated,” and suggest creating new keys every three to six months. Because each realm signs with its own keys, an API that trusts realm home rejects a perfectly valid token from realm lab. That is the isolation working, not a bug.

Email is per realm. The email settings live under each realm’s Email tab and drive address verification and password resets. A second realm means configuring SMTP a second time, the first hint that extra realms cost upkeep.

Brute force protection is per realm, and off. The brute force docs state that “Brute force detection is disabled by default.” If a realm’s login page is reachable from outside your LAN, switch it on in that realm. Enabling it in master does nothing for home.

A realm is one JSON document

Under the console, a realm is a single JSON object. Exports produce it, imports consume it, and its top-level fields map onto the tabs above. The field names below come from Keycloak’s RealmRepresentation class, trimmed to a lab realm’s essentials (lifespans are in seconds):

{
  "realm": "lab",
  "displayName": "Lab (safe to break)",
  "enabled": true,
  "sslRequired": "external",
  "registrationAllowed": false,
  "loginWithEmailAllowed": true,
  "verifyEmail": false,
  "bruteForceProtected": true,
  "passwordPolicy": "length(12)",
  "accessTokenLifespan": 300,
  "ssoSessionIdleTimeout": 1800,
  "ssoSessionMaxLifespan": 36000,
  "groups": [
    { "name": "admins" },
    { "name": "family" }
  ],
  "users": [],
  "clients": []
}

Started with --import-realm, Keycloak imports realm files from /opt/keycloak/data/import, and the import and export guide says it skips any realm that already exists. That makes a throwaway lab realm a two-file job:

# compose.yaml, with lab.json saved in ./realms/
services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.8.0
    command: start-dev --import-realm
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: change-me
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./realms:/opt/keycloak/data/import:ro

start-dev keeps its data inside the container, so docker compose down followed by docker compose up -d hands you a fresh lab realm. That is a feature for a realm you break on purpose and a disaster for the one your family logs into. The real deployment wants start, PostgreSQL and the settings covered in Keycloak behind a reverse proxy.

What is not inside a realm?

Anything that configures the server process sits outside every realm: hostname, proxy headers, database connection, caches, HTTP and TLS, feature flags and the bootstrap admin. These are kc.sh options or KC_ environment variables, and they apply to all realms at once. The configuration reference groups them under headings like Database, Hostname v2, Proxy, Cache and Feature.

One small exception: the hostname guide lists “Realm configuration for frontend URL” among the sources Keycloak uses to resolve its URLs, so a realm can advertise its own public URL. Leave it empty unless you know why you need it.

Two consequences matter on a single mini-PC:

• A realm is not a resource boundary. Every realm shares one JVM, one database and one upgrade. If the container runs out of memory, every realm goes down together. Realm data, including clients, roles and groups, sits in a local realms cache capped at 10,000 entries by default, per the caching guide. Keycloak memory usage and heap sizing covers what that costs in heap.
• A realm export is not a backup. The import and export guide warns the process “has limitations to be used as a backup and restore mechanism,” and server settings are not in it at all. Run pg_dump on a schedule and rehearse a restore. Keep realm exports in git because they diff nicely, not because they will save you.

Why should apps stay out of the master realm?

Because master is the administration realm, and its admin role can manage every other realm on the server. Keycloak creates it at first startup along with the initial admin account, and the getting-started guide says to use it “only for managing Keycloak and not for managing any applications.” Your dashboard client and your partner’s account do not belong next to that.

The separation buys least privilege without extra software. Each realm gets its own admin console at /admin/{realm-name}/console and a built-in realm-management client whose roles, such as realm-admin, manage-users and view-users, cover that realm only, per the per-realm admin docs. The master realm docs go further and describe disabling master entirely in favour of admins defined inside each realm.

For a homelab, that last step is more ceremony than it is worth. The sensible middle ground: one strong master admin stored in your password manager for realm-level surgery, and an ordinary account in the application realm for logging into apps every day. If someone else should reset family passwords, manage-users in that realm is enough.

How many realms does a homelab need?

One application realm, plus master. You, your family and your friends can all live in it, with groups and client roles deciding who reaches which app. A second realm earns its place only for a genuinely separate user population with its own login rules, or for a disposable lab realm rebuilt from JSON like the one above.

Realm-per-app looks tidy in the console and defeats the point of running an identity provider:

• No single sign-on between apps. Sessions belong to a realm, so logging in to the realm guarding your photo library does nothing for the one guarding your dashboards.
• Duplicate accounts. Each person needs an account in each realm, or you wire up brokering between realms to fake it.
• Repeated configuration. SMTP, password policy, brute force settings, themes and key rotation all multiply by the realm count.
• More memory. Each realm’s configuration and clients occupy entries in the realms cache.

If you are building a product for many customer companies rather than a house, Keycloak’s tool is Organizations, which the organizations docs describe as enabling “multi-tenancy within a realm.” Good to know it exists; your homelab does not need it.

The finer realm-versus-client distinction, token scopes and click-by-click creation steps are in Keycloak realms, clients and token design fundamentals.

How does an app know which realm to use?

Through the issuer URL. Every realm publishes its OpenID Connect endpoints under the server’s base URL plus /realms/{realm-name}, and an app given that issuer, or the discovery URL beneath it, finds the rest on its own, per Keycloak’s OIDC endpoint reference. Point an app at the wrong realm and logins fail even with the right password.

Name the realm like a hostname: short, lowercase and not tied to whichever app you set up first. It lands in every app’s config and in the iss claim of every token. If the discovery document shows http://, a container name or the wrong port, the realm is fine and the server’s hostname or proxy settings are not.

If you suspect you will never want a second realm, only a login wall in front of a few apps, authentik vs Keycloak explains why Keycloak may be more server than you need.

FAQ

what is the default realm in keycloak

The default realm is master, which Keycloak creates on first startup together with the initial administrator account. It exists to create and manage other realms, not to hold application users or clients. Create a separate realm, such as home, before registering your first app, and leave master for administration only.

do keycloak realms share a database

Yes, every realm on a Keycloak server lives in the same database, configured once with the server’s database options. A realm separates identities, not storage or compute. That makes backups simple, because one database dump covers every realm, but it also means a database outage or a failed upgrade takes down all realms at once.

can users from one keycloak realm log in to another

Not directly, because a realm only authenticates the users it controls. To let one realm’s accounts into another, configure identity brokering: add the first realm as an OpenID Connect identity provider in the second. Users then sign in through the first realm, and the second realm creates a linked account for them on first login.

how do i export a single keycloak realm

Run kc.sh export with --realm and a --dir or --file target, for example bin/kc.sh export --file home.json --realm home, ideally with the server stopped. Add --users skip to leave accounts out of a config copy. Treat the result as reviewable configuration for git, not as a backup; dump the database for that.

Related across the network

• How to Set Up a Reverse Proxy with Nginx Proxy Manager — selfhostrealm.com
• Install Open WebUI With Docker: Setup Guide — openwebuihq.com