What Is Keycloak and How Does It Work?

Keycloak gives multiple applications a shared place to authenticate users instead of making every application build its own login from scratch.

To understand Keycloak, you first need five concepts: realm, client, user, role, and session. This guide explains those concepts and follows one browser login from the application to Keycloak and back.

What Is Keycloak?

Keycloak is an open-source identity and access management (IAM) server. Instead of building login separately into every application, you can send users to Keycloak to sign in. Keycloak verifies who the user is and then gives the application trusted information about that user.

Beyond basic sign-in, Keycloak can also provide:

• Single sign-on (SSO) across connected applications
• Multi-factor authentication (MFA)
• Password recovery flows
• Integration with LDAP and Active Directory
• Login through external providers such as Google or Microsoft

Single sign-on (SSO) means a user signs in once with Keycloak and can then open other connected applications without entering credentials again while the Keycloak session remains valid.

Think of Keycloak as sitting between people and the software they use:

                      ┌───────────────┐
                      │ LDAP / AD     │
                      │ federation    │
                      └───────▲───────┘
                              │
  Person ─────────────► Keycloak ─────────────► Application
                              │
                      ┌───────▼────────────┐
                      │ External IdP       │
                      │ Google / Entra ID  │
                      └────────────────────┘

Keycloak is not your application database and not a general-purpose user directory for every system in the company by itself. It is the identity layer that applications rely on for authentication, sessions, and identity tokens.

Current upstream releases are in the Keycloak 26.x line. Terminology and defaults in this article match Keycloak 26.7.x unless noted otherwise.

What Problem Does Keycloak Solve?

Without a central identity server, every application tends to grow its own:

• Login form and session cookie
• Password reset flow
• MFA option

Users accumulate separate passwords, and signing in separately to every application becomes a custom integration project.

Keycloak addresses that repetition by giving applications one shared place to:

• Authenticate users once and reuse SSO sessions
• Issue signed tokens or SAML assertions
• Delegate passwords to LDAP or Active Directory
• Apply consistent login policies per realm

Keycloak handles authentication and can provide roles and identity claims that applications use for authorization. It does not automatically decide every business rule inside your application. For example, Keycloak might put an editor role in an access token, but your API still decides which operations that role is allowed to perform.

Keycloak also has Authorization Services for more advanced policy-based access control, but that is separate from the basic SSO concepts covered here.

How Keycloak Works: Login Request Flow

The most useful mental model is one browser login to a web application registered as a Keycloak client. The application does not verify the password itself; it redirects the browser to Keycloak and later receives proof of login.

Walk through a typical OpenID Connect authorization code flow for a web app named storefront-web in realm golinuxcloud:

1. The user opens the application and clicks Sign in.
2. The application redirects the browser to Keycloak. The request identifies the application using its client ID and includes the redirect URI where Keycloak should send the browser after login.
3. Keycloak shows a login page or reuses an existing SSO session.
4. Keycloak authenticates the user locally or through a federated user store such as LDAP. If the user chooses an external identity provider such as Google or Microsoft, Keycloak sends the browser there instead. The external provider authenticates the user and sends the browser back to Keycloak with the authentication result.
5. Keycloak creates a session and redirects the browser to the application’s registered redirect URI with an authorization code.
6. The application exchanges the code for ID, access, and often refresh tokens.
7. The application establishes its signed-in session and uses the access token when it needs to call a protected API. When applicable, a refresh token can obtain new tokens after the access token expires.

These tokens have different jobs:

• ID token — describes the authenticated user
• Access token — presented to APIs when the application calls a protected service
• Refresh token — can obtain new tokens without asking the user to sign in again

  Browser                  Application                 Keycloak
     │                           │                         │
     │── open app ──────────────►│                         │
     │◄── redirect to Keycloak ──│                         │
     │   ──────────────────────── auth request ───────────►│
     │    ◄────────────────────── login page ──────────────│
     │   ──────────────────────── credentials ────────────►│
     │    ◄── redirect + auth code ────────────────────────│
     │── code ──────────────────►│                         │
     │                           │── code + client auth ──►│
     │                           │◄── tokens ──────────────│
     │◄── signed-in app ─────────│                         │

The application does not send the user's password in this exchange. For a confidential web client, it authenticates itself to Keycloak while exchanging the one-time authorization code.

An application also needs to know where Keycloak's login, token, and public-key endpoints are. Instead of configuring each URL separately, OIDC provides one discovery URL that returns this information. For realm golinuxcloud on a local lab host, discovery looks like this (trimmed):

http://127.0.0.1:8080/realms/golinuxcloud/.well-known/openid-configuration

A fragment of the JSON shows where clients find the authorization and token URLs:

{
  "issuer": "http://127.0.0.1:8080/realms/golinuxcloud",
  "authorization_endpoint": "http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/auth",
  "token_endpoint": "http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/token",
  "jwks_uri": "http://127.0.0.1:8080/realms/golinuxcloud/protocol/openid-connect/certs"
}

After login, Keycloak can issue an ID token containing information about the authenticated user and an access token that the application can present to APIs.

The jwks_uri tells the application where to obtain Keycloak's public signing keys. Before trusting a token, the application typically checks:

• The token signature verifies against those public keys
• The token came from the expected Keycloak realm (issuer claim)
• The token has not expired (expiration claim)

This article stops at the flow; grant types, client authentication, and scope design belong in dedicated OIDC guides and in Keycloak clients explained.

Keycloak Core Concepts: Realm, Client, User, Role and Session

Keycloak organizes these objects within realms. Users, clients, roles, and login sessions belong to a particular realm.

After the table, three details help avoid common beginner confusion:

• A realm is a separate security space — alice in one realm is not the same person as alice in another
• Despite the name, a Keycloak client usually represents an application or API, not an end user's computer
• A role such as viewer is only a label until an application uses it — Keycloak can put viewer in Alice's access token, but orders-api still decides what a viewer may do

  Realm: golinuxcloud
  ├── Users: alice, bob
  ├── Groups: support-team
  ├── Roles: realm roles + per-client roles
  ├── Clients: storefront-web, orders-api
  ├── Sessions: alice signed in at 09:15
  └── Identity providers / user federation (optional)

A realm role belongs to the entire realm, while a client role belongs to one specific client. Keycloak can include these roles in tokens so applications can use them when making access decisions. The dedicated Keycloak realm roles vs client roles guide explains token mappings and the realm_access / resource_access fields.

The master realm is special because it is created for managing the Keycloak server and its realms. Application users should normally live in dedicated realms rather than in master. Keycloak realms explained covers isolation, multi-tenancy, and when to add another realm.

Keycloak as an Identity Provider and Identity Broker

Two phrases sound similar but attach at different points in the architecture.

Keycloak as your application's IdP

• An identity provider (IdP) is the system an application trusts to authenticate a user and provide identity information
• When your application uses Keycloak for login, Keycloak is that IdP — the browser signs in at Keycloak and returns with tokens Keycloak issued

Identity brokering

• The application still communicates with Keycloak, but Keycloak sends the user to another provider for login — Google, Microsoft Entra ID, Okta, or a partner SAML IdP
• The external provider authenticates the user and sends the browser back to Keycloak
• Keycloak maps the external account to a Keycloak user in the realm while the application integration stays pointed at Keycloak

  Application ──► Keycloak ──► external OIDC/SAML IdP
                     │
                     └── creates or links local user + session

Brokering is common for “Sign in with …” buttons while keeping one client configuration. User federation is different: Keycloak connects its user model to an external store such as LDAP or Active Directory instead of redirecting the browser to another IdP for login.

User Federation with LDAP and Active Directory

User federation lets Keycloak connect a realm to an existing LDAP or Active Directory directory. This lets users continue using accounts that already exist in the company directory instead of creating a completely separate Keycloak password database.

Depending on the federation settings, Keycloak can:

• Keep a local copy of some user information imported from the directory
• Read user information from the directory when needed
• Leave password checking with LDAP or Active Directory

                 Keycloak
                    │
          ┌─────────┴─────────┐
          │                   │
     Local users        LDAP / Active Directory
          │                    │
          │             federated user data
          │             and/or credentials
          │                    │
          └─────────┬──────────┘
                    │
              authenticated user
                    │
              session + tokens

Federation and brokering answer different questions:

• User federation — where does Keycloak get user information and credentials?
• Identity brokering — does Keycloak redirect the user to another identity provider to sign in?

This article does not configure either path; separate guides cover configuration in detail.

Keycloak Protocols: OIDC, OAuth 2.0 and SAML

Keycloak speaks several standards so different application stacks can integrate without custom plugins:

OAuth 2.0 is primarily an authorization framework for obtaining access tokens. OpenID Connect builds identity and login on top of OAuth 2.0, which is why applications normally use OIDC, rather than plain OAuth, when the goal is user sign-in.

For a new application, OIDC is usually the first protocol to consider. SAML remains common when integrating with enterprise software that specifically supports or requires it. Keycloak can register OIDC clients and SAML clients in the same realm; the client type you pick must match what the application supports.

Protocol choice does not change the core objects — realms, users, sessions — but it changes the wire format your developers implement. Separate guides cover configuration in detail.

When to Use Keycloak—and When Not To

The decision is usually less about whether Keycloak can provide a feature and more about whether your team wants to operate the identity platform itself.

Upstream Keycloak vs Red Hat build of Keycloak

The examples on this site use the upstream open-source Keycloak project from keycloak.org. Red Hat build of Keycloak is a productized downstream with Red Hat support and release engineering; core concepts map closely, but support boundaries and some packaging differ.

Once the terminology makes sense, install Keycloak and try the same objects yourself. Pick one install path:

• Container lab — Install Keycloak with Podman on a Linux host
• ZIP plus systemd — Install Keycloak on Linux and Run Keycloak as a systemd service
• Kubernetes — Install Keycloak on Kubernetes with the Keycloak Operator

Create a dedicated realm, register a client, and add a test user using the realm, client, and user guides linked earlier in this article. Read Keycloak start vs start-dev before you copy a tutorial container into production.

Summary

Keycloak gives applications a central identity service for login, SSO, MFA, sessions, and standard protocols such as OpenID Connect and SAML. Applications register as clients inside a realm, and users authenticate either directly with Keycloak, through a federated user store such as LDAP, or through an external identity provider.

After authentication, Keycloak issues tokens or SAML assertions containing information the application can validate and use. The next practical step is to install Keycloak, create a dedicated realm, and register your first client.

References

• Keycloak documentation — product overview and guides
• Server Administration Guide — Core concepts — realms, clients, users, sessions, federation, and identity brokering
• Securing applications and services with OpenID Connect — how clients use OIDC endpoints
• OpenID Connect Discovery 1.0 — metadata document format
• OAuth 2.0 Authorization Framework — authorization code flow foundation