Understanding Keycloak Foundations — Realms, Clients, Roles, Scopes & Authentication Flows

Introduction

In the previous posts of this series, I explored:

• Why identity has become a foundational concern in modern systems
• How concepts like authentication, authorization, tokens, OAuth 2.0, and OpenID Connect (OIDC) help establish trust across applications and services

Those posts focused primarily on understanding the why and the core building blocks behind modern identity systems.

But “How are all these ideas actually organized inside a real identity platform? “

Up until this point, most of what I explored was conceptual:

• How systems establish trust
• How tokens propagate identity
• How authentication differs from authorization

But modern applications do not implement these ideas from scratch every time. Instead, they rely on dedicated identity platforms that centralize and standardize these responsibilities.

This is where I started diving deeper into Keycloak.

At first glance, Keycloak felt overwhelming:

• Realms
• Clients
• Scopes
• Roles
• Flows
• Identity Providers

There were many moving parts, and initially it felt difficult to understand how everything connected together.

In this post, I’ll focus on building a mental model of how Keycloak works:

• What its core building blocks are
• Why they exist
• How they connect together to solve identity and access management problems in modern systems

The goal here is to understand How Keycloak thinks about identity

What is Keycloak Really?

At its core, Keycloak acts as:

• A centralized identity system
• A trust broker between applications and services
• A token issuer and validator
• A platform for managing authentication and authorization consistently across systems

Why Systems Need Something Like Keycloak

In smaller applications, authentication logic is often embedded directly into the application itself:

• User tables in the database
• Password validation inside backend services
• Session handling managed locally

This works initially.

But as systems grow:

• Multiple applications appear
• APIs get introduced
• Mobile apps need access
• Services communicate with other services
• External integrations become necessary

At this point, identity starts becoming fragmented.

Different systems may:

• Implement authentication differently
• Handle authorization inconsistently
• Maintain separate user stores
• Duplicate security logic everywhere

This is exactly the kind of problem centralized identity systems try to solve.

Keycloak as a Centralized Identity Layer

One mental model that helps better understand Keycloak better is that it sits between users, applications, and services as the system responsible for identity and trust.

Instead of every application handling authentication independently:

• Applications redirect users to Keycloak
• Keycloak authenticates users
• Keycloak issues tokens
• Applications and services trust those tokens

This creates a centralized and standardized identity flow across the ecosystem.

What Keycloak Actually Manages

As I explored further, I found that Keycloak handles many responsibilities that applications would otherwise need to build themselves:

Identity Management

• Users
• Credentials
• Sessions

Authentication

• Login flows
• Multi-factor authentication
• External identity providers

Authorization

• Roles
• Groups
• Access control

Token Management

• Access tokens
• ID tokens
• Refresh tokens

Federation & Single Sign-On

• Login across multiple applications
• Integration with external providers like Google or GitHub

A Real-World Perspective

In banking and enterprise systems, this centralization becomes especially valuable. Instead of:

• Every application implementing its own authentication logic
• Every API validating credentials differently
• Every service managing users independently

a centralized identity platform creates:

• Consistent trust boundaries
• Standardized authentication flows
• Unified access management
• Better security visibility and control

What Makes Identity Systems Difficult

One aspect is that is that identity systems are fundamentally distributed systems. The challenge is not just: “Can the user log in?”

The harder problem is:

• How identity propagates across systems
• How trust is established between services
• How tokens are validated consistently
• How authorization rules remain manageable at scale

This is the problem space Keycloak is designed to address.

In the next section, we will explore concepts like Realms, Clients, Roles, Scopes, which are crucial for understanding Keycloak.

Building a Mental Model of Keycloak

A useful way to think about Keycloak is this: It provides a structured environment where applications, users, permissions, and authentication flows can all exist in a centralized and controlled manner.

Inside this environment:

• Users authenticate
• Applications request identity
• Tokens are issued
• Permissions are enforced
• Trust is established between systems

All through a standardized model.

The core concepts of Keycloak along with its purpose is shown below.

Core Building Blocks

A Simplified Identity Flow

At a high level, the flow inside Keycloak resembles like below :

User → Keycloak → Token → Application/API

Breaking this down:

1. A user authenticates with Keycloak
2. Keycloak verifies identity
3. Keycloak issues tokens
4. Applications and APIs trust those tokens
5. Access decisions are made based on roles/scopes/claims

This simple flow is the foundation for many modern authentication systems.

Why These Concepts Exist

Each of the KeyCloak concept can be mapped to a real-world problem.

Realms: Need isolation between environments or organizations.

Clients: Need a way to represent applications and services.

Roles: Need centralized permission management.

Scopes: Need controlled access to identity and APIs.

Relating This to Real Systems

In enterprise and banking systems, this structure becomes extremely important.

A typical ecosystem may contain:

• Customer-facing applications
• Internal employee portals
• Mobile apps
• APIs
• Partner integrations

Without a centralized identity model:

• Authentication logic becomes duplicated
• Permissions become inconsistent
• Trust between services becomes difficult to manage

This is where systems like Keycloak provide structure and standardization.

In the next section , we will talk about Realm , one of the key concept of KeyCloak.

Understanding Realms

What a Realm Really Represents

A realm is essentially a self-contained identity ecosystem.

Inside a realm, Keycloak manages:

• Users
• Credentials
• Roles
• Clients
• Groups
• Authentication flows
• Tokens

Everything within the realm operates under its own isolated identity model.

This means:

• Users in one realm are separate from users in another
• Roles are isolated
• Tokens belong to a specific realm
• Authentication configurations are independent

In other words: A realm defines the scope within which identity and trust exist.

Why Isolation Matters

As I explored more real-world architectures, this idea of isolation started making much more sense.

Different systems often have completely different:

• Users
• Security requirements
• Authentication mechanisms
• Access policies

Trying to manage all of them in a single shared identity space quickly becomes difficult.

Realms solve this by creating clear boundaries.

A Banking Example

Thinking through this from a banking perspective helped me understand realms much better.

Imagine a banking ecosystem containing:

• Customer-facing applications
• Internal employee systems
• Partner integrations

These systems may require:

• Different user bases
• Different authentication policies
• Different access controls
• Different trust boundaries

Instead of mixing everything together, separate realms can isolate these concerns.

For example:

• Retail Banking Realm
• Internal Employees Realm
• Partner Integrations Realm

Each realm can independently manage:

• Users
• Roles
• Authentication flows
• Tokens
• Clients

without affecting the others.

Realms as Security Boundaries

One thing I found particularly important is that realms are not just organizational constructs.

They are security boundaries.

For example:

• Tokens issued in one realm are generally not trusted in another
• Authentication sessions are isolated
• Roles and permissions do not automatically cross realms

This separation helps reduce:

• Accidental trust leakage
• Authorization confusion
• Cross-system security risks

How Everything Connects Back to the Realm

As I explored Keycloak further, I noticed that almost every major concept exists within a realm:

• Clients belong to realms
• Users belong to realms
• Roles belong to realms
• Authentication flows belong to realms

Thus, understanding the realm helps explain the structure of the entire system.

In the next section, we will look at Clients.

Understanding Clients

A client is essentially: An entity that interacts with Keycloak to authenticate users, obtain tokens, or validate identity.

This can include:

• Web applications
• Mobile applications
• Backend APIs
• Internal services
• Partner systems

In other words: Clients are the consumers of identity.

Thinking About This in Real Systems

In a modern banking architecture, there may be many applications interacting with the same identity platform.

For example:

• Mobile Banking App
• Internet Banking Portal
• Internal Employee Dashboard
• Transaction APIs
• Partner Services

Each of these systems may:

• Redirect users to Keycloak for login
• Receive tokens from Keycloak
• Validate identity and permissions
• Enforce authorization rules

Inside Keycloak, each of these systems can be represented as a separate client.

Why Clients Exist

One thing that became clear while learning Keycloak is that different applications often have different security requirements.

For example:

• A mobile app behaves differently from a backend API
• Public-facing applications cannot securely store secrets
• Internal services may require stronger trust relationships
• APIs may only validate tokens without handling login directly

Clients help Keycloak model these differences in a structured way.

Different Types of Clients

As I explored further, I noticed that Keycloak categorizes clients based on how they interact with the identity system.

The general three types were:

Public Clients

Public clients are applications that cannot securely store credentials. These typically include Browser-based applications and Mobile Apps.

Since users can inspect these environments, storing secrets securely becomes difficult.

These clients typically:

• Redirect users to Keycloak for authentication
• Receive tokens after login
• Operate without client secrets

Confidential Clients

Confidential clients are applications that are capable of securely storing credentials. Examples include Backend services and Server-side applications.

These clients:

• Authenticate themselves to Keycloak
• Use client secrets or certificates
• Participate in more secure server-side flows

This model is common in enterprise backend systems.

Bearer-Only Clients

Get Aditya Ramaswamy’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Bearer-only clients do not initiate login flows themselves. Instead they only validate incoming bearer tokens.

This is commonly used for:

• Backend APIs
• Resource servers

In this model: The API trusts Keycloak-issued tokens but does not handle user login directly.

How Clients Fit into the Bigger Picture

Clients essentially become the bridge between:

• Users
• Applications
• Tokens
• Authorization

inside the identity ecosystem.

Keycloak — Clients

Why Proper Client Configuration Matters

While exploring identity systems, I also realized how critical proper client configuration is.

Misconfigured clients can lead to:

• Token leakage
• Weak authentication flows
• Incorrect redirect handling
• Overly broad trust relationships

This is one reason identity systems become security-sensitive very quickly.

A Real-World Perspective

In banking systems, clients often map directly to business systems:

• Customer applications
• Internal operations portals
• API gateways
• Partner ecosystems

Managing them centrally through an identity platform provides:

• Consistent authentication
• Standardized token handling
• Better trust management
• Centralized security control

In the next section, we will take a look at how Keycloak decides what a user or application is allowed to do?

Roles, Groups, and Authorization

Once I started understanding how users and applications fit into Keycloak, the next question naturally became: How does the system decide what a user is allowed to do?

This is where concepts like:

• Roles
• Groups
• Authorization

started becoming much more meaningful.

And interestingly, this is also where identity systems begin moving beyond authentication into actual access control.

Inside Keycloak, roles and groups help model the permissions in a centralized and manageable way.

Understanding Roles

One simple way to understand roles is that it represents permissions or responsibilities within the system.

For example, in a banking environment , there can be the below roles:

• customer
• support-agent
• auditor
• admin

Each role may grant access to different capabilities.

For example:

• A customer may view personal account information
• A support agent may assist users but not perform transactions
• An admin may manage system-level operations

Instead of hardcoding these rules into every application, Keycloak allows them to be centrally managed.

Realm Roles vs Client Roles

Realm roles apply across the entire realm.

These are useful for:

• Broad system-wide permissions
• Shared organizational roles

Examples include admin, employee, auditor

Client roles are specific to a particular application or service.

For example: transaction-approver, report-viewer , account-editor

These permissions only make sense within that specific client/application context. This separation helps avoid overly broad access models.

Understanding Groups

Groups help identity systems manage users at scale.

Instead of assigning roles individually to every user:

• Users can be organized into groups
• Roles can then be assigned to groups

For example: Retail Customers , Corporate Customers , Operations Team ,
Fraud Monitoring Team

This creates a much more manageable authorization structure.

Why Groups Become Important

In real systems:

• Users change teams
• Responsibilities evolve
• Access requirements shift over time

Without groups:

• Role management quickly becomes difficult to maintain

Groups provide:

• Organizational structure
• Easier permission management
• Better scalability for large user bases

How Authorization Fits Into Tokens

An interesting part is that the authorization information eventually becomes part of the token itself.

For example, tokens may contain:

• Roles
• Group memberships
• Scopes
• Permissions

This allows backend services to make authorization decisions without repeatedly querying the identity provider.

A Banking Perspective

In banking systems, authorization becomes especially sensitive because access boundaries are critical.

For example:

• A teller should not access internal audit systems
• A support user may only view limited customer information
• Certain transactions may require elevated approval roles

Centralized authorization helps ensure:

• Consistent access control
• Reduced privilege leakage
• Easier auditing and governance

Identity systems become difficult not because authentication is hard, but because authorization becomes complex over time.

Managing:

• Roles
• Exceptions
• Organizational structures
• Cross-system permissions

at scale is often one of the biggest operational challenges.

This is why centralized identity and authorization systems become so valuable in enterprise environments.

In the next section we will explore Scopes which will connect KeyCloak to OAuth and Tokens.

Understanding Scopes and Claims

Scopes are deeply connected to how modern identity systems control access and share identity information in a structured way.

What a Scope Really Represents

One way to think about scopes is that it is A way of defining what information or level of access is being requested.

Instead of applications automatically receiving unrestricted access, they explicitly request specific scopes.

For example: openid profile email

This tells the identity system:

• What identity information the application needs
• What level of access is being requested
• What should be included in the resulting tokens

Why Scopes Exist

As systems become more distributed, applications rarely need unlimited access.

For example:

• A reporting service may only need read access
• A profile page may only require basic user information
• A payment API may require elevated permissions

Scopes help limit and structure this access. This aligns closely with one of the core ideas behind OAuth 2.0: Delegated and controlled access.

Understanding Claims

While scopes define what can be accessed, claims represent: The actual identity or authorization data carried inside tokens.

Claims are pieces of information embedded within tokens.

Examples include:

• Username
• Email
• Roles
• Groups
• User ID
• Token expiry
• Issuer information

In many ways: Claims become the context backend services use to make decisions.

How Scopes and Claims Work Together

One can think of scopes and claims as follows:

• Scopes → determine requested access/information
• Claims → carry that information inside tokens

For example:

• Requesting the email scope may result in an email claim being added to the token
• Requesting profile may include user profile-related claims

This creates a standardized way for applications to receive identity information.

How Keycloak Uses Scopes

Inside Keycloak, scopes help control:

• What identity data appears in tokens
• What permissions are associated with tokens
• How applications interact with APIs

This becomes particularly important when different applications require different levels of access.

For example:

• A mobile app may only require basic profile information
• An internal admin portal may require additional authorization claims
• Partner systems may need restricted token scopes

Scopes help structure these access boundaries cleanly.

Scopes and Claims

A Banking Perspective

In banking systems, limiting access becomes extremely important.

Not every application should receive:

• Full customer information
• Administrative permissions
• Broad API access

For example:

• A notification service may only require customer contact information
• A reporting application may only need read-only access
• Sensitive transaction APIs may require elevated scopes and authorization claims

This principle of limited and controlled access is one of the foundations of secure identity systems.

At this point, the major Keycloak building blocks started fitting together:

• Realms isolate identity
• Clients consume identity
• Roles and groups manage permissions
• Scopes and claims shape token access and information

The final piece was understanding: How authentication itself flows through the system.

Understanding Authentication Flows and Token Issuance

At this point we have explored the individual pieces of Keycloak:

• Realms
• Clients
• Roles
• Groups
• Scopes
• Tokens

So How does the entire authentication process actually flow through the system?

What an Authentication Flow Really Is

Initially, I assumed authentication was simply:

• User enters credentials
• System validates them
• Token gets issued

But modern identity systems are much more flexible than that.

An authentication flow is essentially: A sequence of steps that defines how identity verification happens.

Depending on the system requirements, this may include:

• Username/password validation
• Multi-factor authentication (MFA)
• OTP verification
• Social login
• Identity federation
• Conditional authentication rules

Effectively Authentication is not a single action — it’s an orchestrated process.

A Simplified Flow

One mental model that helped me visualize the process was:

User → Application → Keycloak → Authentication → Token → Application/API

Breaking this down:

1. User tries to access an application
2. Application redirects user to Keycloak
3. Keycloak performs authentication
4. Keycloak issues tokens
5. Application/API trusts the token
6. Authorization decisions happen using claims/roles/scopes

This simple flow powers many modern identity systems.

Token Issuance

One thing I found particularly interesting was how central token issuance is to the entire architecture.

Once authentication succeeds:

• Keycloak generates signed tokens
• Tokens carry identity and authorization information
• Applications and services trust those tokens

These tokens may include:

• User identity
• Roles
• Groups
• Scopes
• Expiry information
• Issuer details

In many ways: Tokens become the portable representation of trust.

Different Types of Tokens

The authentication flows often produce different kinds of tokens.

The most common ones are:

• Access Token: Used to access APIs and services
• ID Token: Carries user identity information
• Refresh Token: Used to obtain new access tokens

Understanding this distinction between these tokens makes it easier to understand OAuth and OIDC flows.

Why Authentication Flows Matter

The authentication flows allow identity systems to adapt to different security requirements.

For example:

• Customer login may require OTP verification
• Internal employee systems may require MFA
• Partner integrations may use federated identity providers
• APIs may use service-to-service authentication flows

Instead of every application implementing this logic independently: Keycloak centralizes and standardizes the process.

A Banking Perspective

In banking systems, authentication flows are rarely simple.

Different operations may require different trust levels:

• Viewing account details
• Performing transactions
• Approving high-value payments
• Accessing internal administrative systems

Authentication flows help enforce these trust boundaries consistently.

For example:

• Sensitive operations may trigger additional verification
• Internal systems may enforce stricter authentication policies
• Different user categories may follow different login flows

This flexibility becomes extremely important in enterprise identity systems.

Authentication flows, token issuance, scopes, and authorization all work together to maintain that trust model.

And that’s what makes identity platforms fundamentally different from simple login systems.

And with these foundations now in place, the next step is finally moving into the hands-on side of the journey:

• Setting up Keycloak
• Creating realms and clients
• Exploring authentication flows
• Issuing and validating tokens
• Integrating applications and APIs

That’s what I will write in the next post.