Realms
What is a realm?
Section titled “What is a realm?”A realm is the top-level container in Keycloak. Every object in Keycloak — users, clients, roles, identity providers, token policies — belongs to exactly one realm. Realms are completely isolated from each other: a user in realm shop cannot log in to an application registered in realm blog, and their sessions are never shared.
You can think of a realm as a tenant in a multi-tenant SaaS system, except that each realm is managed entirely within one Keycloak server.
The master realm
Section titled “The master realm”Keycloak is installed with one realm already in place: master. The master realm has a special purpose: it is the administrative realm. When you open the Keycloak admin console and log in, you are authenticating against master.
The master realm can create and manage other realms, but it should never be used to register your own applications or store your application’s users. Mixing your app users with the administrative super-users of master is a serious security risk.
Creating a realm
Section titled “Creating a realm”- Open the Keycloak admin console at
http://localhost:8080and sign in with your admin credentials. - In the top-left corner, click the realm name drop-down (it initially shows Keycloak or master).
- Click Create realm.
- In the Realm name field, enter a short, lowercase, hyphen-separated name for your realm (e.g.,
my-app). - Make sure Enabled is toggled on.
- Click Create.
Keycloak creates the realm and switches your console context into it. All subsequent configuration (clients, roles, users) will belong to this new realm.
A tour of realm settings
Section titled “A tour of realm settings”After creating a realm, click Realm settings in the left sidebar. The settings are organised into tabs:
General
Section titled “General”- Display name — a human-readable name shown on the login page.
- Frontend URL — override the URL Keycloak uses to build redirect links (useful behind a reverse proxy).
- HTML display name — supports HTML for branded login pages.
- User registration — allow self-service sign-up.
- Forgot password — enable the password reset flow (requires email configured).
- Remember me — let users stay logged in across browser restarts.
- Verify email — require users to confirm their email address after registration.
- Login with email — allow users to enter their email address instead of a username.
Configure the SMTP server Keycloak uses to send verification and password-reset emails. Required if you enable any email-triggered flows.
Tokens
Section titled “Tokens”Key settings that control token lifetimes and behaviour:
| Setting | Default | What it controls |
|---|---|---|
| Access token lifespan | 5 min | How long an access token is valid |
| SSO session idle | 30 min | Session expires if idle for this long |
| SSO session max | 10 hours | Hard limit on session length |
| Refresh token lifespan | Matches SSO session | How long a refresh token can be used |
Shorter access-token lifespans reduce the window of exposure if a token is stolen, at the cost of more frequent refreshes.
Keycloak automatically generates cryptographic keys for signing tokens. The Keys tab shows the active key providers. For production, you should rotate keys periodically. The RS256 provider is the default and produces JWTs signed with an RSA private key; clients verify signatures using the public key available at the realm’s JWKS endpoint:
http://localhost:8080/realms/{realm-name}/protocol/openid-connect/certs