What Is an Authentication Flow?

An Authentication Flow is a configurable, ordered sequence of steps — called executions — that Keycloak walks a user through in order to authenticate them for a particular purpose. It is not a single fixed algorithm baked permanently into Keycloak’s code; it’s a structure an administrator can inspect, rearrange, extend, and even completely replace through the admin console, without writing a single line of application code.

Executions: The Individual Steps

Each individual step inside a flow is called an execution. An execution is usually a specific authenticator — a piece of logic that performs one particular check, like “verify username and password,” “verify a one-time code,” or “check whether this device has been seen before.” A flow, at its simplest, is just an ordered list of these executions.

Why Configurable Flows Exist at All

Different organizations have wildly different requirements for what counts as an acceptable login. A small internal tool might be satisfied with a plain password. A bank might insist on a password plus a one-time code, and only for logins from an unrecognized device. A healthcare portal might need to check that a user has accepted an updated consent form before finishing login. Rather than hardcoding one rigid login sequence and forcing every organization to live with it (or fork Keycloak’s source code to change it), Keycloak exposes the entire sequence as an editable structure — the Authentication Flow — so each organization can shape login to its own actual risk profile and regulatory needs.

Flows Are Scoped to a Realm

Like nearly everything else covered in this series, Authentication Flows live inside a specific Realm. Two separate Realms can have entirely different flows — one Realm’s employee login might require a hardware security key, while a completely separate customer-facing Realm on the very same Keycloak server might allow a simple password, because these two populations of users and their risk profiles are entirely distinct.

Distinguishing a Flow From What It Produces

It’s worth being precise about what a flow actually decides, versus what happens afterward. A flow’s job ends the moment it determines, definitively, whether this particular login attempt succeeded or failed. Everything covered elsewhere in this series about tokens, claims, and Roles happens only after a flow has already concluded successfully — the flow is exclusively concerned with the question “should this login be allowed to proceed at all,” never with what the resulting session or token subsequently contains.

A Flow Is Not the Same as a Single Login Page

A common early misunderstanding is picturing a flow as simply “the login page.” In reality, a single flow frequently spans several distinct screens shown one after another — a username-and-password form, followed by a one-time-code entry screen, possibly followed by a prompt to register a new second factor if none exists yet. Each of these separate screens corresponds to a distinct execution inside the same overall flow, not a separate flow in its own right.

Flows Also Cover What a User Sees Before Any Credential Is Entered

It’s worth noting that a flow’s first execution doesn’t always have to be a credential check at all. An organization offering multiple external identity providers alongside local login might place an Identity Provider Redirector execution first, presenting the user with a choice of login options before any password field ever appears. The flow, in this sense, governs the entire shape of the login journey from the very first screen a user sees through to the moment their identity is finally confirmed, not merely the credential-checking portion in isolation.

Why the Browser Flow Gets the Most Attention

Among all the built-in flows, the Browser flow is overwhelmingly the one organizations spend the most time customizing, simply because it governs the everyday, highest-volume login path that the largest share of real users experience most often. The other flows matter and deserve their own review, but a security or user-experience initiative aimed at “how people log in” is, in the vast majority of cases, really an initiative aimed specifically at reshaping this one particular flow.

Every execution inside a flow has one of four requirement types assigned to it, and this setting is what actually determines the flow’s real behavior, far more than the mere order of the steps:

How Sibling Executions Combine

The requirement type of one execution only makes complete sense in the context of its siblings — the other executions at the very same level of the flow. A set of sibling executions marked Alternative means “succeed at any one of these,” while a Required step among the same siblings means “this one, no matter what, on top of whatever else succeeds.” Misreading how siblings combine is the single most common source of a flow behaving unexpectedly.

A Worked Example of Combination Logic

Consider a top level containing exactly three executions: a Required username/password form, and two Alternative options — an OTP form and a WebAuthn security-key check — both siblings of each other but not of the password form. Reading this correctly: the password form must succeed, full stop, no way around it. Then, separately, the user must succeed at either the OTP form or the security-key check, but never both and never neither. Change that OTP form’s requirement type from Alternative to Required, and the meaning shifts entirely — now every single user must pass both the password form and the OTP form, and the WebAuthn option becomes an entirely unreachable, dead configuration that no login path ever actually uses.

Disabled Steps Are Not the Same as Deleted Steps

It’s worth dwelling on the Disabled requirement type specifically, since it’s easy to underestimate. A Disabled execution remains fully configured — its settings, its position in the flow, any attached conditions — but Keycloak simply skips over it entirely during evaluation, as though it were never placed in the flow at all. This is genuinely useful for temporarily turning off a step (during an incident, or while troubleshooting) without losing the work of having configured it, and then flipping it back on later with nothing to reconfigure from scratch.

Why a Flat List Isn’t Enough

Consider a Realm that wants to offer two entirely different second factors — an authenticator app or a hardware security key — where a user only needs to succeed at one of them, but that whole “second factor” concept should itself only apply if the user has actually enrolled in either. Expressing this cleanly requires nesting: a Conditional sub-flow (only entered if the user has some second factor configured) containing two Alternative executions (either of which is acceptable) inside it.

graph TD
    Root["Browser Flow"]
    Root --> Req1["Required: Username/Password Form"]
    Root --> Cond["Conditional Sub-Flow:
Second Factor Required?"]
    Cond --> Check["Condition: User Has
OTP or Security Key Configured"]
    Cond --> Alt1["Alternative: OTP Form"]
    Cond --> Alt2["Alternative: Security Key (WebAuthn)"]
    

Sub-Flows Can Nest Further

A sub-flow can itself contain another sub-flow, allowing genuinely sophisticated decision trees — though, as with composite Roles discussed elsewhere in this series, nesting several layers deep makes a flow considerably harder for an administrator to reason about at a glance. Depth should be used deliberately, not accumulated by accident over successive edits.

Sub-Flows Without a Condition

Not every sub-flow needs to be Conditional. A plain sub-flow, given a Required or Alternative type of its own, is simply a way of grouping several executions together and treating that entire group as a single unit for the purposes of the parent flow’s own combination logic. This is useful purely for organizational clarity — bundling, say, every step related to “second factor entry” together under one labeled group — even when no conditional branching is actually involved.

Reading a Flow Diagram Correctly

When reviewing a flow in the admin console, indentation in the visual tree corresponds directly to nesting depth, and the requirement type shown alongside each row applies to that row relative to its own immediate siblings — not to the flow as a whole. A newcomer reading a complex flow for the first time should always ask, for any given execution, “who exactly are this row’s siblings, and what’s required among them?” rather than trying to judge overall strictness from position or indentation alone.

What a Condition Actually Checks

A condition attached to a sub-flow is itself a small piece of logic evaluating something about the current login attempt — common built-in conditions check things like whether the user carries a specific Realm Role, whether a specific user attribute is set to a certain value, or whether the requesting Client matches certain criteria. If the condition’s check passes, the sub-flow’s contents run as normal; if not, they’re skipped entirely, as if they weren’t part of the flow at all for this particular login.

The Classic Use Case: Risk-Based Step-Up Authentication

One of the most common real-world patterns built on this mechanism is requiring a stronger second factor only for users holding a sensitive Realm Role (like “admin” or “finance-approver”), while ordinary users continue through a lighter-weight path. This is achieved entirely through a Conditional sub-flow checking Role membership — no application code changes needed, since the decision lives entirely inside the flow’s own configuration.

Conditions Can Also Look at the Client or the Request Itself

Role and attribute checks are the most commonly used conditions, but they’re not the only ones available. A condition can also examine which specific Client initiated the login, letting an organization apply a stricter flow only when a particularly sensitive application is the one being logged into, even for a user who might face a lighter path when logging into a different, lower-risk application within the very same Realm. This lets the same underlying user population face different effective requirements depending on what they’re actually trying to access, not just who they are.

Conditions Are Evaluated Before Their Sub-Flow’s Contents, Never After

It’s worth being explicit about ordering here, since it matters for correctness: a condition is always checked first, before any execution nested inside its sub-flow runs. There is no way for something happening inside the sub-flow to retroactively change whether that sub-flow was entered in the first place — the decision to branch is made once, upfront, based only on information already available at that point in the login.

Design. An administrator maps out the desired sequence of steps and branching logic, typically starting from a copy of a built-in flow rather than an entirely blank one, as covered in Chapter 9.

Binding. The finished flow is connected to a specific purpose at the Realm level — for example, designating a custom flow as the Realm’s active Browser flow, replacing the built-in default for that purpose.

Active Use. Every subsequent login of that type is evaluated against the bound flow, exactly as walked through in Chapter 5.

Testing After Changes. Any edit to a flow that’s actively bound takes effect immediately for the next login attempt — there is no separate “publish” step, which makes careful testing before binding a change to production especially important.

Iteration. As requirements change — a new second factor is adopted, a regulatory requirement shifts, a conditional check needs refining — the flow is edited and, if the change is significant, tested against a copy before being rebound.

graph LR
    A["Flow Designed
(often copied from a built-in flow)"] --> B["Tested
(ideally in a non-production Realm)"]
    B --> C["Bound to a Purpose
(e.g. set as the Browser flow)"]
    C --> D["Active on Every
Matching Login"]
    D --> E{"Requirements Change?"}
    E -->|"Yes"| F["Flow Edited"]
    F --> B
    

Why Not Edit the Built-In Flow Directly?

Keycloak’s built-in flows are typically protected from direct editing, and even where direct editing is technically possible, doing so is strongly discouraged. Built-in flows serve as a known-good baseline and, in some upgrade scenarios, may be reset or updated by Keycloak itself, potentially discarding direct edits.

The Standard Pattern

The overwhelming majority of real customizations follow the same three-step pattern: duplicate the relevant built-in flow under a new name, make the desired changes to executions and requirement types on that copy, and then bind that new, customized flow to the Realm in place of the original built-in one. This preserves the original as an untouched reference point that can always be restored by simply re-binding back to it.

What “Binding” Actually Means in Practice

A finished, customized flow accomplishes nothing on its own until it’s connected to a purpose through the Realm’s flow bindings — a small set of Realm-level settings, each naming which flow currently serves as, for example, “the Browser flow” or “the Direct Grant flow” for that Realm. Multiple customized flows can exist side by side inside the same Realm at once, sitting unused, and this is a deliberate, safe way to prepare a replacement in advance: build and thoroughly review the new flow first, and only flip the binding over once it’s fully ready, keeping the previous flow intact and instantly available to roll back to.

Rolling Back a Bad Change Quickly

Precisely because the original built-in flow is left untouched under the copy-then-modify pattern, recovering from a bad customization is usually as simple as re-pointing the relevant flow binding back to the original, restoring the previous, known-working behavior for every user immediately. This rollback path is one of the strongest practical reasons the copy-then-modify pattern is treated as close to mandatory rather than merely a suggestion.

Naming Conventions Matter More Than They Seem

As an organization accumulates several customized flows and sub-flows over time — one for standard employees, one for elevated-privilege accounts, one mid-rollout of a new second factor — clear, descriptive names for each become essential. A flow named simply “browser copy” tells a future administrator nothing about its purpose six months later, whereas a name like “browser – finance-approver-otp-enforced” communicates its intent at a glance, without needing to open and trace through the flow itself just to understand what it’s for.

The Authenticator SPI

Keycloak exposes a Service Provider Interface (SPI) specifically for authentication, letting developers implement a completely custom authenticator — a new kind of execution — with its own logic, its own configuration options, and its own screen if it needs to interact with the user. Once installed on the server, a custom authenticator appears in the admin console’s execution list exactly like any built-in one, ready to be dragged into a flow at whatever position and requirement type an administrator chooses.

Because a custom authenticator runs directly inside the login pipeline for every affected user, it deserves the same careful review, testing, and monitoring as any other security-critical code — a subtle bug here can either wrongly lock out legitimate users or, in the worst case, be tricked into letting an illegitimate login through.

When a Custom Authenticator Is (and Isn’t) the Right Call

Reaching for a custom authenticator is appropriate when a genuinely organization-specific check has no equivalent among Keycloak’s built-in executions and conditions — a proprietary risk score, an integration with an internal fraud-detection system, a check against a legacy identity store that predates the Keycloak rollout. It is usually the wrong call when the same outcome can be achieved by combining existing built-in conditions and executions in a Conditional sub-flow, since configuration changes carry far less ongoing maintenance burden than custom code that needs to be kept compatible with future Keycloak upgrades.

Deployment and Upgrade Considerations

A custom authenticator is deployed as a piece of installed server-side code, not a database record like a flow’s configuration, which means upgrading Keycloak itself can occasionally require revisiting a custom authenticator’s compatibility with the new version. Organizations that build custom authenticators typically track this as an explicit line item in their upgrade planning, rather than assuming configuration-only changes (like flow edits) and code-level extensions (like custom authenticators) carry the same upgrade risk.

Required vs. Alternative Is a Security-Critical Distinction

An administrator intending to mandate a second factor for every user, but accidentally configuring the OTP execution as Alternative rather than Required alongside the password form, has not actually enforced anything — a user can simply succeed via whichever Alternative path is easiest, silently skipping the intended second factor entirely. This exact class of misconfiguration has caused real-world incidents where an organization believed it had mandatory MFA in place when it did not.

Locking Yourself Out

A poorly tested Required execution, or a custom authenticator with a bug, can render every single account in a Realm unable to log in — including administrator accounts needed to fix the very flow causing the problem. Maintaining a separate, carefully protected recovery path (such as a break-glass administrator account outside the affected flow, or documented server-level recovery steps) is a genuine operational necessity, not an optional precaution.

Conditions Are Only as Trustworthy as What They Check

A Conditional sub-flow that bases a security-relevant decision on a user attribute deserves scrutiny over who can actually set or change that attribute’s value. If an ordinary user could freely edit an attribute that a condition treats as a signal for “this user doesn’t need a second factor,” the condition becomes a self-service way to opt out of a control the organization intended to be mandatory. Security-relevant conditions should generally rely on Roles and attributes that only an administrator (or a trusted, separately audited process) can set — never anything an end user can adjust about their own account.

The First Broker Login Flow Deserves Its Own Scrutiny

Because the First Broker Login flow governs what happens the very first time a user arrives through an external identity provider, it often includes logic deciding whether to automatically link that external identity to an existing local account matching the same email address. Misconfiguring this specific flow has, in real incidents elsewhere in the industry, allowed an attacker who controls an email address to link into and take over an existing account under that same address at a different, unrelated identity provider — a reminder that this particular flow deserves as much careful review as the everyday Browser flow, even though it’s exercised far less frequently.

The Direct Grant Flow Carries Its Own Distinct Risk

Because the Direct Grant flow collects a username and password directly inside an application’s own form, rather than redirecting to Keycloak’s dedicated login page, it inherently cannot include any execution that needs to show the user an interactive, Keycloak-hosted screen mid-flow — a security-key prompt or a redirect to an external identity provider simply has nowhere to render inside this particular flow’s model. Organizations relying on Direct Grant for any user-facing login (as opposed to purely backend, machine-to-machine use) should recognize this ceiling explicitly, since it constrains which second factors can realistically be enforced there compared to the considerably more flexible Browser flow.

Reviewing Flows as Part of a Broader Security Audit

A periodic security review of an organization’s Keycloak deployment should treat Authentication Flow configuration as its own distinct checklist item, separate from reviewing Roles, Clients, or Required Actions. Because a flow’s real behavior depends on the interplay between step order, requirement types, and nested conditions, a reviewer benefits from actually testing a representative login for each meaningfully different user population — not merely reading the configuration and assuming its intent matches its actual, evaluated behavior.

Correlating Flow Behavior With Support Volume

A practical, easily overlooked metric is simply correlating spikes in login-related support tickets with recent flow changes. Because a flow edit takes effect immediately, a support-ticket spike beginning shortly after a specific change is a strong, fast signal pointing directly at the likely cause — often faster to notice through this correlation than through detailed per-execution metrics alone, especially in smaller organizations without a dedicated identity engineering team.

Watching for Unexpected Alternative-Path Usage

When a flow offers multiple Alternative paths (say, password login alongside SSO), tracking the relative volume flowing through each path over time can reveal whether an intended migration (like the passwordless rollout described in Chapter 15) is actually progressing, or whether users are quietly sticking with a legacy path far longer than expected, signaling a need for clearer in-product guidance nudging them toward the newer option.

Good Patterns

• Copy-then-modify: always start a custom flow from a duplicated built-in flow, never editing built-ins directly
• Shallow, well-documented nesting: use sub-flows deliberately, and document what each Conditional branch is meant to achieve
• Test in a non-production Realm first: especially for any Required execution change that could affect every user
• Maintain a break-glass recovery path: a way to regain administrative access that sits outside whatever flow is being changed

Anti-patterns to Avoid