Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Realms, Users and Roles

Realms in Depth: Isolation, Settings, Keys and Import/Export

Understand Keycloak realms: when to use one or many, realm settings, token and session lifetimes, signing keys, brute-force protection and moving realms with export and import.

A realm is the unit of isolation in Keycloak and the first design decision you make. Get it right and everything else is simple; get it wrong and you will be migrating users later. This lesson explains how to choose the number of realms, what a realm contains, the settings that matter most for security, and how to copy a realm between servers.

What a realm isolates

Inside one realm you find users and their credentials, clients, roles, groups, client scopes, identity providers, user federation, authentication flows, themes, email settings, events and keys. Across realms nothing is shared:

  • a user in realm shop cannot sign in to a client of realm staff,
  • tokens from different realms have different issuers (iss) and different signing keys,
  • there is no SSO between realms (each realm has its own login session),
  • admins of one realm cannot see another, except through the master realm.

How many realms?

Strategy Use when Trade-off
One realm for all apps One organization, one user base, SSO across apps Simplest; all apps share users and password policy
One realm per environment (dev, staging, prod) You run separate servers anyway Not needed if each environment has its own server
One realm per tenant B2B SaaS where each customer has its own users, branding or identity providers Strong isolation, more admin work, slower with thousands of realms
Organizations feature inside one realm Many customer organizations with shared infrastructure Newer feature; fewer realms to operate

Rules of thumb: do not use master for applications, and do not create a realm per application, because that destroys single sign-on. Keycloak handles dozens or hundreds of realms; tens of thousands need careful capacity planning.

Key realm settings

Open Realm settings and learn these tabs.

  • General: Realm ID (the URL name, cannot be changed later), display name, whether the realm is enabled.
  • Login: User registration (self sign-up), Forgot password, Remember me, Login with email, Email as username, Verify email.
  • Email: SMTP host, port, sender address, encryption, authentication. Without it, verification and reset mails do not work.
  • Themes: choose login, account and email themes (see the customization chapter).
  • Sessions: SSO Session Idle (logged out after inactivity), SSO Session Max (absolute lifetime), Remember me variants.
  • Tokens: Access Token Lifespan (keep it short, minutes), Access Token Lifespan For Implicit Flow, Client login timeout, Action token lifespans (links in reset mails).
  • Security defenses: HTTP headers and Brute force detection (lock after N failures, wait time, permanent lockout option).

Sensible start values: access tokens of 5 minutes or less, SSO idle 30 minutes, SSO max 10 hours for staff-facing apps, shorter for sensitive ones.

Realm keys

Each realm has its own cryptographic keys, shown in Realm settings > Keys:

  • RSA signing key (algorithm RS256), used to sign tokens. Your APIs fetch the public part from the jwks_uri and verify signatures.
  • AES key for internal encryption.
  • HMAC key for symmetric signing needed by some features.

Each key has a priority; the highest-priority active key signs new tokens. Rotation means adding a new key provider with higher priority, then later passive or disabled on the old one, so old tokens stay verifiable until they expire. If your application caches the JWKS (it should), it needs a way to refresh when it sees an unknown kid (key ID). Never export a realm and publish its private keys.

Events

Under Realm settings > Events you can store user events (login, logout, failed login, code-to-token, register, update password) and admin events (every admin change, optionally with the representation). Choose a retention (expiration) and which event types to save. Events are your audit trail and a basis for alerting; large realms should also send them to a log system through an event listener.

Moving a realm: export and import

Realms are portable as JSON.

Terminal
# Stop the server or use a separate working copy, then:
bin/kc.sh export --dir /tmp/export --realm demo --users realm_file
bin/kc.sh import --dir /tmp/export

Notes:

  • --users controls whether users are exported (skip, realm_file, same_file, different_files).
  • Exports contain secrets such as client secrets (masked as ********** in some fields) and may contain password hashes, so protect the files.
  • Import at start with start-dev --import-realm reads every file in data/import.
  • The admin console also has Realm settings > Action > Partial export / import for configuration without users.

Treat exports as the starting point of configuration as code (also see the operations chapter): commit a sanitized realm JSON and apply it in CI.

Disabling and deleting

Disabling a realm (General tab) blocks all logins and token operations for it without deleting data. Deleting removes users, clients, sessions and events permanently. There is no recycle bin, so export first.

A lifetime calculator (stand-in)

Session and token lifetimes interact in ways that surprise people. This runnable stand-in is not Keycloak code; it models the rule that a refresh token cannot outlive the SSO session, and shows when a user will have to log in again.

Node.js Stand-in: when must the user log in again?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

With a 4-minute refresh the session survives until the 10-hour maximum; a user who leaves for 45 minutes loses it at the 30-minute idle limit.

A realm checklist (stand-in)

Use this stand-in to audit a realm configuration object against the recommendations above.

Node.js Stand-in: realm settings audit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The sslRequired value in the audit is a real realm setting (all, external or none). The default external allows plain HTTP only from private addresses such as localhost; setting none is for experiments.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should you avoid creating one realm per application?

    SSO sessions exist inside a realm. Use one realm for apps that share users.
  2. 2. What is the effect of rotating realm keys by adding a new key with higher priority?

    The highest-priority active key signs. A passive old key remains in the JWKS until its tokens expire.
  3. 3. Which tab is where you configure brute force detection?

    Security defenses holds HTTP response headers and brute force detection.
  4. 4. What should you remember about realm export files?

    Exports can include credentials and client secrets. Store and share them like secrets.

Summary

  • A realm isolates users, clients, roles, keys and settings; there is no SSO across realms.
  • Use one realm for apps sharing users; per-tenant realms only for strong isolation; never apps in master.
  • Tune sessions, token lifespans, email, themes and brute-force protection under Realm settings.
  • Each realm has its own signing keys; rotate by priority and keep old keys passive for a while.
  • Export and import move realms as JSON; protect the files and enable events for auditing.

Next: Users, Credentials and Password Policies