Realms, Clients & Roles

🔐 Run Keycloak with Docker first

Start Keycloak in dev mode:

docker run --name keycloak -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

Then open http://localhost:8080 and sign in to the admin console with admin / admin.

start-dev uses an in-memory database — perfect for learning. Use a real database and start for production.

What this module covers

This module teaches the three building blocks that every Keycloak deployment is made of: realms, clients, and roles. Before you can secure a single application with Keycloak, you need to understand what these concepts are, how they relate to each other, and how to create and configure them in the admin console.

By the end of this module you will be able to:

Create and configure a dedicated realm for your application.
Register an application (client) with Keycloak.
Understand the difference between public and confidential clients and choose the right one.
Create realm roles and client roles and assign them to users.
Read a decoded JWT and find roles inside it.

The three building blocks

Realm

A realm is Keycloak’s top-level isolation boundary. Think of it as a tenant: it has its own set of users, clients, roles, identity providers, and token settings. Nothing leaks between realms — a session in realm A cannot authenticate a user into realm B.

Keycloak ships with one realm pre-created: master. The master realm is the administrative realm — you use it to log in to the admin console and manage other realms. You should never deploy your own applications inside the master realm.

Client

A client is any application that delegates authentication to Keycloak. A client could be a single-page app (SPA), a mobile app, a server-side web application, or a machine-to-machine service. Each client registers itself in a realm, declares its redirect URIs, and receives tokens from Keycloak after a user authenticates.

Role

A role is a named permission that can be attached to users or groups. There are two flavours:

Realm roles — defined at the realm level and available to any client in that realm.
Client roles — defined on a specific client and scoped to that client.

Roles show up in tokens so your application can make authorisation decisions without calling Keycloak again.

How they fit together

flowchart TD
  R[Realm] --> U[Users]
  R --> RR[Realm-level roles]
  R --> C[Clients]
  C --> CR[Client roles]
  C --> RU[Valid redirect URIs / settings]

How a realm contains users, roles, and clients

A user in a realm can be assigned realm roles and client roles. When the user authenticates through a client, the resulting token contains those roles so the client can enforce access control.

Lessons in this module

Lesson	What you will learn
Realms	Create and configure a realm
Clients	Register an application as a client
Client Types	Public vs confidential clients and PKCE
Roles	Realm roles, client roles, and composite roles