Before touching Keycloak itself, you need the vocabulary around identity and access management that every other concept builds on.

Keycloak is a free, open-source tool that handles login, user accounts, and permissions for other applications, so developers don’t have to build their own login system from scratch for every app they create.

IAM is the general term for systems that manage who a user is (identity) and what they’re allowed to do (access) within one or more applications. Keycloak is one specific tool that provides IAM.

Authentication is the process of proving who you are — typically by entering a username and password, or using something like a fingerprint or a one-time code sent to your phone.

Authorization happens after authentication and decides what an already-identified user is allowed to do — for example, whether they can view a page, edit a record, or access an admin panel.

Single Sign-On lets a user log in once and then access multiple different applications without having to log in again separately for each one — Keycloak is commonly used specifically to provide this experience.

An identity provider is the system responsible for authenticating users and confirming their identity to other applications. Keycloak itself acts as an identity provider for the apps connected to it.

A service provider is an application that relies on an identity provider (like Keycloak) to handle login, rather than managing its own usernames and passwords directly.

Keycloak is open source, meaning its code is publicly available for anyone to inspect, use, and modify for free, which is one reason it’s widely trusted and adopted for handling something as sensitive as user login.

These are the handful of objects you’ll see constantly inside Keycloak’s admin console — understanding them makes everything else click into place.

A realm is an isolated space in Keycloak that manages its own set of users, applications, and settings — completely separate from any other realm. Most organizations create one realm for their entire company or product.

In Keycloak, a “client” refers to an application (a website, mobile app, or backend service) that is registered with Keycloak so it can use Keycloak for login and permission checks.

A user is an individual person’s account stored inside a realm, including their username, credentials, and profile information like email or name.

A role represents a permission or a level of access, such as “admin” or “editor,” that can be assigned to users to control what they’re allowed to do.

A group is a way to organize multiple users together and assign roles or settings to the whole group at once, instead of configuring each user individually.

The master realm is a special, default realm used specifically to manage Keycloak itself — creating other realms, managing overall server settings, and controlling top-level administrators.

The admin console is the web-based dashboard where administrators configure realms, clients, users, and roles — it’s the main interface you use to manage everything in Keycloak.

This chapter covers what actually happens when a user tries to log in through Keycloak.

A login flow is the sequence of steps a user goes through to prove their identity — such as entering a username and password, and possibly a second verification step afterward.

Instead of each application building its own login form, Keycloak provides a ready-made login page that users are redirected to, which keeps the login experience consistent and secure across all connected applications.

This is the most common authentication method, where a user proves their identity by entering a username (or email) along with a matching secret password.

A credential is any piece of information used to prove identity, most commonly a password, but it could also be a one-time code or a security key, depending on how authentication is configured.

Required actions are tasks a user must complete before they can finish logging in — for example, being forced to update an expired password or verify their email address on first login.

A password policy defines the rules passwords must follow in a realm, such as minimum length or requiring a mix of letters and numbers, to encourage stronger, harder-to-guess passwords.

Brute force detection temporarily locks or slows down an account after too many failed login attempts, protecting against automated programs trying to guess a password repeatedly.

flowchart LR
    U["User"] -->|1. Wants to log in| App["Client Application"]
    App -->|2. Redirect| KC["Keycloak Login Page"]
    U -->|3. Enters credentials| KC
    KC -->|4. Verifies identity| KC
    KC -->|5. Sends token| App
    App -->|6. User is logged in| U
    

Keycloak communicates with applications using well-known industry standards. This chapter introduces them at a beginner level.

OAuth 2.0 is an industry-standard protocol that allows one application to access resources on behalf of a user without ever seeing that user’s password — Keycloak implements this standard to handle secure logins.

OpenID Connect is a layer built on top of OAuth 2.0 specifically designed for verifying a user’s identity (rather than just granting access to resources) — it’s the most common protocol Keycloak uses for login.

SAML (Security Assertion Markup Language) is an older, XML-based protocol also used for single sign-on, still common in some enterprise systems, and supported by Keycloak alongside OpenID Connect.

An access token is a piece of digital proof, issued by Keycloak after a successful login, that an application uses to confirm the user is authenticated and to check what they’re allowed to access.

A refresh token is a longer-lived credential used to obtain a new access token once the original one expires, without forcing the user to log in again from scratch.

An ID token contains basic information about who the user is (like their name or email), and is meant to be read directly by the application, unlike the access token which is meant for accessing resources.

A JWT is a compact, digitally signed text format used to represent tokens like access tokens and ID tokens — Keycloak issues its tokens in this format so applications can verify they haven’t been tampered with.

This chapter covers the settings you configure when connecting a real application to Keycloak.

A client ID is a unique name that identifies a specific application when it talks to Keycloak, similar to a username for the application itself rather than for a person.

A client secret is a private password-like value used by confidential applications to prove their own identity to Keycloak, kept hidden and never exposed to end users or browsers.

A redirect URI is the exact web address Keycloak is allowed to send a user back to after a successful login — configuring this correctly prevents login responses from being sent to the wrong, potentially malicious, destination.

A public client (like a single-page web app or mobile app) cannot safely store a secret, so it relies on other protections, while a confidential client (like a backend server) can securely store a client secret and use it during login.

Client scopes define what specific pieces of information (like email or profile details) are included in the tokens issued to a particular client, controlling how much data the application receives about the user.

A client adapter is a small library that helps an application integrate with Keycloak more easily, handling details like redirecting users to log in and validating tokens, so developers don’t have to build that logic manually.

Roles are how Keycloak expresses “what a user is allowed to do” — this chapter covers the beginner-level role concepts.

A realm role is a permission that exists at the realm level and can potentially apply across multiple applications within that same realm, such as a general “admin” role.

A client role is a permission specific to one particular application, such as “invoice-editor” that only makes sense within a billing application, rather than realm-wide.

A composite role is a role that automatically includes one or more other roles, so assigning one composite role to a user effectively grants them several permissions at once.

Role mapping is the act of assigning a specific role to a specific user or group, connecting the permission (role) to the person who should have it.

Default roles are roles automatically assigned to every new user created in a realm, useful for ensuring all users start with some baseline set of permissions without manual setup.

Keycloak can either store users itself or connect to existing user directories — here are the beginner concepts around that.

User federation lets Keycloak connect to an existing external system (like a company directory) that already stores users, instead of requiring every user to be recreated inside Keycloak from scratch.

LDAP is a common protocol many organizations already use to store employee accounts — Keycloak can connect to an LDAP directory through user federation, so existing company logins work without duplication.

User attributes are extra pieces of information stored on a user’s profile beyond the basics, such as a department name or an employee ID, which can be customized per organization’s needs.

A user session represents an active, logged-in period for a user — Keycloak tracks sessions so it knows a user is still logged in, and can end that session if the user logs out or it expires.

The account console is a self-service page where an individual end user (not an administrator) can update their own profile, change their password, or review their active sessions.

A few final concepts around how Keycloak is actually run and customized in the real world.

Standalone mode refers to running a single Keycloak server instance directly, typically used for development or small deployments, as opposed to a larger clustered setup.

Docker deployment means running Keycloak inside a lightweight, portable container, which makes it easy to start, stop, and move a Keycloak instance consistently across different machines.

Keycloak stores all of its data — realms, users, roles, and settings — in a backing database (such as PostgreSQL), which persists this information even if the Keycloak server itself restarts.

Themes let you customize the look and feel of Keycloak’s login and account pages, so they can match your company’s branding instead of using the default Keycloak design.

Events logging records important activities like logins, failed login attempts, and account changes, which helps administrators monitor usage and investigate suspicious activity later.

Not at the beginner stage. Keycloak handles most of the OAuth 2.0 complexity for you — a basic understanding of tokens and login flows is enough to get started using it in an application.

Yes — through realms and clients, a single Keycloak server can manage login and permissions for many completely separate applications, each configured as its own client, optionally within separate realms.

A realm role can conceptually apply across the whole realm, while a client role is scoped specifically to one application — use client roles when a permission only makes sense within one particular app.

No — because it’s free and open source, Keycloak is used by projects of all sizes, from small personal apps to large enterprise systems needing centralized login across dozens of applications.

Not necessarily — with custom themes, the login page can be fully rebranded to look like part of your own application, so users may never realize Keycloak is working behind the scenes.