Learn Keycloak - Architecture & Core Concepts

#Introduction

Episode 2 introduced the four identity protocols supported by Keycloak. Episode 3 unpacks the internals of Keycloak itself: the core concepts that form its data model, the architectural components that make it up, the configurable authentication flows, and the token types that flow through it. After this episode, you'll be comfortable navigating the admin console because every menu there maps to the concepts discussed.

#Keycloak Overview

Keycloak is an open-source Identity and Access Management (IAM) platform developed by Red Hat. A few important facts:

Open source — open code with a large community and a license friendly to commercial use.
Red Hat SSO — the commercial version based on Keycloak, backed by vendor support.
Cloud-native architecture — runs as a Java application on a server, easy to containerize and orchestrate.
High availability support — supports clustering, cache distribution, and load balancing.
Extensive protocol support — OAuth 2.0, OIDC, SAML 2.0, and LDAP integration.

#Core Concepts

Keycloak's data model is built on several core concepts:

Concept	Definition	Analogy
Realm	Isolation space for users, clients, roles, and configuration	Tenant or security domain
Client	An application connected to Keycloak	Your applications (web, mobile, API)
User	End user who performs authentication	Employees, customers
Role	A named permission that can be granted to users or groups	Role label, e.g. admin
Group	A collection of users managed together	Department, team
Identity Provider	External authentication source	Google, LDAP, SAML IdP
Identity Broker	Bridge to external identity providers	Cross-domain federation

Realm is the most important concept: it is the isolation boundary. Two different realms can't see each other's users or clients. That's why the common practice is to create one realm per environment or per application.

Client represents an application requesting authentication. Each client has its own configuration: access type, redirect URIs, and the protocol used.

Role and group are the foundation of authorization. A role states "what you may do", a group states "who is in a group", and the combination of both simplifies granting permissions at scale.

An Identity Provider is an external authentication source you can connect — e.g. a corporate LDAP or a social login provider. An Identity Broker is the mechanism that connects Keycloak to that IdP, so external users can sign in without needing a new local account.

A practice worth remembering from the start: identify which concept you're touching in the admin console. Every sidebar menu — Realm Settings, Clients, Users, Roles, Groups — is a direct representation of the concepts above.

#Keycloak Architecture

Architecturally, Keycloak consists of several components:

Component	Function
Authentication server	The heart of Keycloak: accepts authentication requests, issues tokens
Admin console	Web interface for managing realms, clients, users, roles, and configuration
Account management console	Web interface for users to manage their own profile and sessions
Database	Stores users, configuration, and events; backends include PostgreSQL, MySQL, and others
Theme engine	Templating system for login page and console appearance
Event system	Records logins, admin actions, and errors for audit

Beyond the web consoles, all admin capabilities are available through the Admin REST API. You can do anything you can do in the admin console via the API, which matters for automation:

Example of accessing the Admin REST API

curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=admin123" \
  -d "grant_type=password"

The token response from grant_type=password above can be used as a bearer token to call admin endpoints like GET /admin/realms. This pattern will become the basis of automation in many upcoming episodes.

For production, the database backend is recommended to be PostgreSQL or MySQL. The start-dev development mode uses a local file database, but for availability and reliability, an external database is the primary choice.

#Authentication Flows

Keycloak manages authentication flows as a configurable sequence of steps. The built-in flows most commonly used:

Browser flow — the main flow for user login in a browser, including the username and password form.
Registration flow — the new user registration flow.
Reset credentials flow — the password reset flow.
Direct grant flow — direct login via API with username and password, like the curl example above.
Login flow — a general term for a sequence of interactive authentication steps.

Each flow is actually a chain of executors running in sequence. A simple example of a browser flow:

The browser requests authentication at the authorization endpoint.
The form executor displays the login page and validates credentials.
If successful, Keycloak creates an SSO session.
The browser is redirected back to the application with a code.

By understanding this chain, you can add custom steps like OTP, WebAuthn, or email verification in the middle of a flow.

You can set which flow is active per realm, and even create custom flows for specific needs like OTP or WebAuthn.

#Token Types

Tokens are Keycloak's main currency. Four types you need to understand:

Token Type	Used For	Characteristics
Access token	Accessing resources at the resource server	Short-lived, carries scopes
ID token	Proving the user's identity to the application	Unique to OIDC, carries profile claims
Refresh token	Getting a new access token	Long-lived, can be rotated
Token introspection	Validating a token at the authority	Called by the resource server

Token lifetimes can be configured in Keycloak: access tokens typically live for minutes, refresh tokens live longer, and SSO sessions have their own timeout. The right configuration balances security and user convenience.

Two supporting mechanisms that often appear in the documentation:

Token introspection — the resource server asks Keycloak whether a token is still valid and active.
Token exchange — exchanging one form of token for another token suitable for a different context.

#Closing

Episode 3 dissected Keycloak's architecture: the realm concept as the isolation boundary, clients as applications, user/role/group as the foundation of authorization, the authentication server components along with consoles and database, the various authentication flows, and the token types that flow through it.

Key takeaways:

The realm is the main isolation boundary — a realm's users and clients aren't visible in another realm.
All admin operations are available via API — the Admin REST API opens the door to automation.
Use an external database for production — PostgreSQL or MySQL replaces the development database.
Tokens have different roles — access tokens, ID tokens, and refresh tokens don't replace each other.

In the next episode (episode 4), you'll dive into OAuth 2.0 fundamentals — the four main roles, endpoint and scope components, and all the grant types along with when to use them.