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.

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 an embedded Infinispan cache. In a cluster, those caches replicate between nodes, so cluster discovery and cache ownership settings decide whether losing a node also logs users out. Session data lives in heap, so both session count and token size drive memory use.

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. Back up the database, not just the exported configuration, since the database holds users, sessions, and signing keys.