Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Concepts and Setup

Keycloak Core Concepts: Realms, Clients, Users, Roles and Tokens

Learn the Keycloak object model: realm, client, user, role, group, client scope, mapper, session and token, and how they relate, with a runnable model stand-in.

Keycloak has a small number of core objects, and almost every feature is a combination of them. If you understand how a realm contains clients and users, how roles and groups attach to users, and how scopes and mappers shape tokens, the admin console stops being a maze. This lesson is the map of the whole course.

The object model

flowchart TD
  R["Realm"] --> U["Users"]
  R --> G["Groups"]
  R --> C["Clients"]
  R --> RR["Realm roles"]
  R --> CS["Client scopes"]
  C --> CR["Client roles"]
  C --> CS
  U -->|"member of"| G
  U -->|"has"| RR
  U -->|"has"| CR
  G -->|"grants"| RR
  CS --> M["Protocol mappers"]
  M --> T["Claims in tokens"]

Everything lives inside a realm.

Realm

A realm is an isolated space with its own users, credentials, clients, roles, groups, identity providers and settings. Users in one realm cannot log into another, and an admin of one realm cannot see another (except the master realm admins, who manage the server). Typical patterns: one realm per environment (dev, test, prod), or one per tenant, or a single realm for one organization. Realms are covered in depth in Realms in Depth.

Client

A client is an application or API that asks Keycloak to authenticate users or to issue tokens. Two kinds matter:

  • Public clients run where secrets cannot be hidden: single-page apps, mobile apps. They authenticate users with the authorization code flow and PKCE.
  • Confidential clients run on a server and can hold a secret (or a key pair). They authenticate to Keycloak too, for example with a client ID and secret.

A bearer-only-style API (a resource server) does not ask users to log in; it only validates tokens. In current Keycloak you model it as a client that you never use for login, or you simply configure your API to trust the realm.

User, credential, attribute

A user has a username, optional email and names, a set of credentials (password hash, OTP secret, WebAuthn keys), attributes (custom data) and required actions (things they must do at next login, such as verifying email). Users can come from Keycloak's own database or be read from LDAP through federation.

Roles and groups

  • A realm role is a named permission label across the realm, for example admin or customer.
  • A client role belongs to one client, such as invoice-app: approver.
  • A composite role contains other roles, so assigning one grants all.
  • A group is a set of users in a tree. Roles and attributes assigned to a group are inherited by its members and by subgroups.

Roles answer "what kind of user is this?"; your app maps them to behavior.

Client scopes and protocol mappers

A client scope is a reusable bundle that a client can request through the OAuth scope parameter. Each scope holds protocol mappers, small rules that put data into tokens: "add the user's email as claim email", "add all realm roles to realm_access", "add a hard-coded claim". Default scopes are always applied; optional scopes only when the client asks for them. This is how you control what ends up in tokens. Details follow in Scopes and Protocol Mappers.

Sessions and tokens

When a user logs in, Keycloak creates a user session (the SSO session) and, for each client used, a client session. Tokens issued in it:

Token Audience Purpose
Access token The API (resource server) Proves authorization; short-lived (minutes)
ID token The client application Proves who the user is (OIDC)
Refresh token Keycloak itself Gets a new access token without a login; longer-lived

Tokens are signed JSON Web Tokens (JWTs). Their anatomy is in Tokens and JWT Claims.

Flows and policies

An authentication flow is the ordered list of steps Keycloak runs at login (cookie check, username and password form, OTP, and so on), each marked required, alternative, conditional or disabled. You can copy a built-in flow and change it. Required actions and policies (password policy, OTP policy, brute force detection) round out the login behavior.

Keycloak and the standards

Keycloak term Standards term
Realm (no standard term; an issuer URL such as https://host/realms/shop)
Client OAuth 2.0 client / OIDC relying party / SAML service provider
Keycloak OAuth 2.0 authorization server / OIDC OpenID provider / SAML identity provider
API OAuth 2.0 resource server

The realm is the issuer: the iss claim of every token is the realm's URL, and each realm has its own signing keys.

A model of the objects (stand-in)

This runnable stand-in is a minimal in-memory model of a realm: it holds roles, groups and users, and computes a user's effective roles the way Keycloak does (direct roles, composite expansion and group inheritance). It is a teaching model, not Keycloak's code.

Node.js Stand-in: realm, roles, groups, effective roles

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.

Notice that carol has support only because of her group, and bob has four roles from one assignment. When your application reads roles from a token, it sees this expanded result.

Mapping a token (stand-in)

A second stand-in shows how scopes and mappers decide what a token contains. A client asks for scopes; each scope contributes claims; default scopes are always included.

Node.js Stand-in: scopes decide claims

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 unknown scope changes nothing: only scopes configured on the client are honored. That is your protection against clients asking for more data than you allow.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a realm provide?

    Users, clients and configuration are scoped to a realm. Realms do not see each other.
  2. 2. Which client type should a single-page application be?

    A browser cannot keep a secret, so public client plus PKCE is the standard choice.
  3. 3. A user is in group /staff/management, which has role manager, and manager is composite with support. What are the user's effective roles?

    Group roles are inherited by members, and composite roles expand to include their child roles.
  4. 4. Which object adds claims such as email to a token?

    Protocol mappers in client scopes turn user data into token claims.

Summary

  • A realm isolates users, clients, roles, groups, providers and settings; its URL is the token issuer.
  • Clients are applications: public (PKCE) or confidential (secret or key).
  • Roles (realm, client, composite) and groups (hierarchical, inherited) express who a user is.
  • Client scopes bundle protocol mappers that shape the claims in tokens.
  • Sessions produce access, ID and refresh tokens; authentication flows define the login steps.

Next: Installing Keycloak from the Distribution