Keycloak Realms, Clients and Token Design Fundamentals

Keycloak is an open source identity and access management server. It issues tokens using OAuth 2.0 and OpenID Connect, federates against existing directories, and centralizes login for applications that should not be implementing authentication themselves. The concepts below are the ones that determine whether a deployment stays maintainable.

Realms Are Isolation Boundaries

A realm is a self contained namespace of users, credentials, roles, groups, clients, and configuration. Users in one realm cannot authenticate against another. The master realm exists to administer the server itself and should not host application users.

The usual mistake is creating a realm per application. That fragments users and forces duplicate account management. Create a realm per population of users who share an identity domain, such as employees versus external customers, and represent each application as a client inside the appropriate realm.

Clients, Scopes and Roles

A client represents an application requesting tokens. Confidential clients can hold a secret and are used by server side applications. Public clients cannot keep a secret, which covers browser and mobile applications, and must rely on the authorization code flow with PKCE rather than any flow that returns tokens directly.

Roles come in two forms. Realm roles apply across the realm, and client roles are scoped to a single application. Assign roles to groups rather than individual users so membership changes do not require touching authorization data. Composite roles bundle other roles and are useful, but deep nesting makes effective permissions hard to reason about.

Client scopes control which claims and permissions can appear in a token. Trimming scopes is the main lever for keeping tokens small, which matters because tokens travel in headers on every request, and because every claim you add is also carried in the cached session objects that occupy heap. That connection is worked through in Keycloak memory usage and heap sizing.

Authentication Flows and Federation

Authentication flows are configurable chains of executions covering login, registration, password reset, and step up authentication. Copy a built in flow before editing it, and keep custom flows minimal, since a misconfigured required execution can lock everyone out of a realm.

User federation connects Keycloak to an existing LDAP or Active Directory source. Decide early whether Keycloak imports users into its own database or reads them on demand, and decide whether the directory or Keycloak owns each attribute. Getting mapper direction wrong is a common cause of attributes silently reverting after a sync.

Identity brokering is a different mechanism. It delegates login to another OIDC or SAML provider rather than reading a user store directly.

Sessions, Tokens and Clustering

Keycloak keeps user and client sessions in embedded Infinispan caches, alongside separate caches for offline sessions, authentication sessions, action tokens, and login failures. On current releases the caching documentation states that session data is stored in the database by default and loaded into those caches on demand, and that the user and client session caches run with a single owner per entry. That changes the old mental model in two ways: a node failure no longer implies losing the sessions it held, and heap requirements no longer scale with a replication factor.

Cache entry limits and token size still drive memory, though, because a cached session holds every claim the token carries. The Keycloak memory and heap sizing calculator turns a login rate and session count into a heap and node estimate, and the reasoning behind it is set out in Keycloak memory usage and heap sizing.

Token lifetimes are a tradeoff. Short access token lifetimes limit the damage from a leaked token but push more traffic to the token endpoint. Refresh tokens carry the real session duration and deserve stricter storage and revocation handling than access tokens.

Operational Habits

Export realm configuration and keep it in version control so a realm can be rebuilt deterministically. Run behind a reverse proxy with the proxy and hostname settings configured explicitly, because incorrect hostname configuration produces issuer mismatches that surface only once clients start validating tokens properly. The specific options, and the symptoms each one fixes, are catalogued in Keycloak hostname and proxy errors. Back up the database, not just the exported configuration, since the database holds users, sessions, and signing keys.

Where to Go Next

Three follow-on questions come up almost immediately after the concepts above are settled:

• How much hardware does this need? See Keycloak memory usage and heap sizing, or run the numbers directly in the sizing calculator.
• Why will nothing work behind my proxy? See Keycloak hostname and proxy errors.
• Is Keycloak the right tool at all? See Keycloak vs authentik vs Authelia for a comparison against the two self-hosted alternatives it is most often weighed against.