Understanding Realms, Clients, and Roles in Keycloak

TL;DR

Realms = isolated identity spaces (great for multi‑tenancy, per‑env separation).
Clients = apps/services using OIDC/SAML. Choose access type: public, confidential, or bearer‑only.
Roles = permissions. Prefer realm roles for cross‑app levels; client roles for per‑app granularity. Use composites to group.

Introduction

Keycloak is a capable open‑source identity and access management platform. The core mental model is simple: realms isolate identities, clients integrate your apps, and roles gate access. Master these three and you can model almost any auth scenario.

Below is a practical tour with screenshots, crisp definitions, and a minimal corporate‑portal example you can clone in minutes.

Realms: Isolated Authentication Spaces

A realm is a self‑contained boundary with its own users, groups, clients, and roles. Use separate realms for tenants or environments (dev/test/prod) rather than overloading one global space.

Good Defaults

Split by environment (Company‑Dev, Company‑Staging, Company‑Prod).
Use separate admin accounts per realm; avoid cross‑realm coupling.
Document realm‑level policies (password rules, JWT lifetimes, themes).

Clients: Applications and Services

A client is any app or service delegating authentication to Keycloak. Most modern stacks use OpenID Connect; SAML is available for legacy integrations.

Key parameters you actually care about:

Client ID

Unique per realm; referenced by your app when starting OIDC flows.

Protocol

Prefer OpenID Connect unless a partner forces SAML 2.0.

Access Type

public (SPA/native), confidential (server‑side with client secret), bearer‑only (APIs that only verify tokens).

Valid Redirect URIs

Whitelist exact origins/paths to block open redirects; avoid wildcards in prod.

Pro tip: Keep Web Origins as strict as possible. For local dev, use explicit http://localhost:3000 entries over *.

Roles: Managing Access Control

Roles model permissions. Assign them to users or groups and read them from tokens in your apps.

Two flavors you will use daily:

Realm Roles

Global to the realm; ideal for org‑wide access levels like admin, editor, viewer.

Client Roles

Scoped to a specific client; great for app‑specific permissions like billing:read.

Composite Roles

A composite contains other roles. Assign one, get many—handy for Admin bundles that imply editor + billing:write + user:manage.

Example: Corporate Portal in 5 Steps

A minimal setup you can run locally. Adjust names/URIs to your stack.

Step 1: Start Keycloak

Use Docker for local dev:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin   quay.io/keycloak/keycloak:25.0.2 start-dev

Step 2: Create a Realm

Create CompanyPortal to isolate identity for the portal.

Top‑left menu → Create realm
Name: CompanyPortal
Save

Step 3: Register Clients

Sidebar → Clients → Create client
Client ID: WebApp · Protocol: openid-connect
Valid Redirect URIs: http://localhost:3000/* (adjust to your app)
Repeat for MobileApp with appropriate URIs

Step 4: Create Roles

Add Admin and User as realm roles.

Sidebar → Realm roles → Create role
Name: Admin → Save; repeat for User

Step 5: Assign Roles

Map roles to users (or groups):

Sidebar → Users → select a user
Role mapping → Assign role → choose roles → Assign

You now have clean isolation (realm), apps wired (clients), and authorization (roles). Ship the portal, read roles from tokens, and enforce access in code.

Common Pitfalls & How to Avoid Them

Wildcards in Redirect URIs. Convenient in dev, dangerous in prod. List exact origins/paths.
Mixing tenants inside one realm. Use one realm per tenant or at least per environment to reduce blast radius.
Assigning roles only to users. Prefer group‑based role mapping; it scales and is auditable.
Leaking secrets in public clients. SPAs/native apps must be public; do not store client secrets there.

FAQ

Realm roles vs client roles — when to use which?

Use realm roles for organization‑wide access levels; client roles for app‑specific permissions. Compose when needed.

Can I share users across realms?

Not directly. Realms are isolated. Use identity brokering or federated identity if you must span realms.

How do I read roles in my app?

Inspect ID/access tokens. In OIDC, roles appear under realm_access.roles and resource_access[client].roles.

Conclusion & Next Steps

Realms isolate, clients integrate, roles authorize. Start with clean boundaries and strict redirect rules; prefer group mappings and composite roles as your system grows.

Continue with my Keycloak + Next.js (App Router) integration guide or the Keycloak + Nginx cluster setup.

Want a sanity check for your auth model? I audit designs and help teams ship secure, frictionless login flows.