What Is a Conditional Flow?

A Conditional Flow (more precisely, a Conditional sub-flow) is a named group of executions nested inside a larger Authentication Flow, whose entire contents are evaluated only if one or more attached condition executions are satisfied first. If the condition isn’t met, Keycloak skips straight past the whole group, as though none of the executions inside it existed for this particular login attempt.

Conditional vs. Ordinary Sub-Flow

An ordinary sub-flow, given a Required or Alternative type, is simply a grouping mechanism — a way to bundle several executions together and treat them as one unit for the purposes of their parent’s own combination logic, with no branching involved at all. A Conditional sub-flow adds exactly one new idea on top of that: an entry gate. Its contents are still evaluated using the same Required/Alternative logic internally, but only for users who first pass through that gate.

Why This Matters More Than It First Appears

Without Conditional Flows, an organization wanting different login requirements for different kinds of users would face an uncomfortable choice: apply the strictest requirement to absolutely everyone (creating unnecessary friction for low-risk users), or maintain several entirely separate flows and somehow route different users to different ones outside of Keycloak’s own configuration (adding external complexity and coordination overhead). Conditional Flows resolve this cleanly, inside one single flow, using nothing but configuration.

One Flow, Many Effective Experiences

It’s worth dwelling on just how significant this single capability is in practice. A single Realm might serve tens of thousands of users spanning ordinary employees, finance staff handling sensitive approvals, contractors on temporary access, and a handful of administrators with far-reaching system access. Without Conditional Flows, satisfying all four groups’ genuinely different risk profiles from within one Realm would be, at best, an awkward compromise. With Conditional Flows, each group can be routed through exactly the login experience appropriate to its own risk level, while every one of them still shares the exact same underlying Realm, the exact same set of Clients, and the exact same overall administrative structure.

The Relationship to Requirement Types, Restated Precisely

Earlier in this series, four requirement types were introduced: Required, Alternative, Disabled, and Conditional. It’s worth being exact about how Conditional relates to the other three. Required and Alternative both describe how a step’s outcome (success or failure) affects its siblings once the step actually runs. Disabled and Conditional both describe whether a step runs at all in the first place — Disabled always skips, unconditionally, for every user; Conditional skips or runs depending on a check performed fresh for each individual login attempt. Conditional is, in this sense, best understood as a dynamic, per-user version of the same underlying idea Disabled expresses statically for everyone.

Why Keycloak Provides a Fixed Set Rather Than a Free-Form Rule Language

It’s reasonable to wonder why Keycloak ships a defined menu of condition types rather than an open-ended scripting language for expressing any imaginable rule. The deliberate trade-off favors safety and auditability: a fixed set of well-tested, well-understood condition types is far easier to review, reason about, and keep secure across upgrades than an arbitrary rule engine that could express nearly anything, including subtle logic errors difficult to catch in review. For the rare case where none of the built-in condition types can express a genuinely custom check, the Authenticator SPI covered elsewhere in this series remains available as an extension point, but it’s deliberately a heavier-weight path than simply picking a built-in condition from a dropdown.

Negating a Condition

Most condition types can also be configured to check for the opposite of their usual meaning — for instance, “user does NOT hold this Role” or “user has NOT yet configured this authenticator.” This negation capability is what makes the paired-branch pattern described in Chapter 7 possible: one Conditional sub-flow checking the positive case, and a second, separate one checking its negation, together covering the full population without any gap or overlap between them.

How It Works

The User Role condition checks whether the currently logging-in user carries a specified Role — either a Realm Role or a Client Role, both covered in depth elsewhere in this series. If the user holds that Role, the condition passes; otherwise it fails, and the sub-flow is skipped for them.

A Practical Nuance: Which Roles Are Visible at This Point

Because the User Role condition checks the user’s Roles as already resolved by the time authentication logic runs, it reflects whatever Role assignments — direct, via Groups, or via composite Roles — were in effect at that moment. A Role change made mid-session doesn’t retroactively alter an already-completed login; it only affects the user’s next fresh login attempt, consistent with how Role changes behave more generally, as covered elsewhere in this series.

Choosing Between a Realm Role and a Client Role for This Purpose

Because the User Role condition can check either scope, it’s worth applying the same one-sentence scoping test covered elsewhere in this series: would this distinction still make sense if a specific application were removed from the picture? An organization-wide “elevated-privilege” designation, meaningful across many internal tools, is naturally expressed as a Realm Role. A distinction meaningful only within one specific application — say, “power-user status inside this one reporting tool” — is better expressed as a Client Role scoped to that Client, keeping the condition’s meaning tightly aligned with where it actually applies.

Group Membership as an Indirect Path to the Same Condition

Because Roles are frequently assigned through Group membership rather than directly to individual users, as covered elsewhere in this series, the User Role condition effectively also captures Group-based assignment for free — a user placed into a Group carrying the “finance-approver” Role satisfies the condition exactly as if that Role had been assigned to them directly. This is one of the more understated benefits of preferring Group-based Role assignment generally: Conditional Flows built on Roles automatically stay correct as Group membership changes, with no separate update needed to the flow itself.

How It Works

The User Attribute condition checks whether a named attribute on the user’s account matches a configured expected value. Attributes are flexible, freeform fields on a user’s profile — things like a department code, a subscription tier, or a custom flag set by an administrative process — that don’t always map neatly onto the broader, more formal concept of a Role.

When to Choose Attribute Over Role

As a general rule, reach for a Role when the distinction represents a stable, meaningful category of user that other parts of the system (authorization checks, reporting, audits) also care about. Reach for an attribute when the distinction is narrower, more temporary, or specific enough that formalizing it as a Role would add more organizational overhead than it’s worth.

Attribute Comparison Nuances

An attribute-based condition typically compares a stored value against an expected one, and it’s worth being precise about what “matches” means for the specific attribute in question. A simple flag like “true” or “false” compares cleanly and unambiguously. A free-text attribute (say, a department name typed inconsistently as “Finance,” “finance,” or “Finance Dept” by different administrators over time) can produce a condition that silently fails to match for some users purely due to inconsistent data entry, not any flaw in the flow’s logic itself. Establishing a clear, consistent convention for how a given attribute’s values are entered — ideally enforced through a controlled administrative process rather than free typing — meaningfully reduces this entire category of quiet, hard-to-diagnose failure.

Attributes Set by External Systems

In many real deployments, the attribute a Conditional Flow checks isn’t set through Keycloak’s own admin console at all, but synchronized in from an external system of record — an HR platform, a customer relationship management system, or a dedicated identity governance tool — through an automated integration. This is a legitimate and common pattern, but it does mean the condition’s real-world behavior depends on that external synchronization running correctly and promptly; a delay or failure in the upstream sync can leave a condition evaluating against stale data for some period of time, worth accounting for when investigating an unexpected result.

How It Works

The User Configured condition checks whether the user has already enrolled in a specific authenticator — for example, whether they’ve already registered an OTP device. This lets a flow behave differently depending on the user’s own enrollment history, rather than any externally assigned Role or attribute.

What Is a Level of Authentication?

An Authentication Context Class Reference (commonly abbreviated ACR) is a standardized way for an application to request, and for an identity provider to report back, how strong a given login actually was — for example, “level 1” might represent a plain password, while “level 2” might represent a password plus a verified second factor. A Level of Authentication (LoA) condition checks whether the login currently in progress needs to reach a specific one of these levels.

Why This Differs From the Other Conditions

Every condition covered so far in this guide checks a fact about the user themselves. The Level of Authentication condition instead checks a fact about the request — specifically, what strength of authentication the requesting application asked for on this particular login attempt. This lets a single application request a stronger login only for a specific sensitive action (like approving a large payment), rather than the strength being fixed purely by who the user is.

How This Interacts With an Already-Existing Session

A particularly useful property of the Level of Authentication condition is that it can force a genuinely fresh check even for a user who already holds a perfectly valid, still-active session at a lower authentication level. Rather than treating “already logged in” as sufficient forever, the application can explicitly demand the session be strengthened, in the moment, for one specific sensitive step — the identity equivalent of a bank asking a customer already standing at the counter to additionally show a second form of identification before authorizing an unusually large withdrawal, even though the teller already greeted them by name moments earlier.

Standardization Benefits Across Multiple Applications

Because ACR/LoA is a standardized concept rather than something Keycloak invented in isolation, multiple applications integrating with the same Realm can express step-up requirements in a consistent, portable way, and a security team can reason about “what does level 2 actually guarantee here” once, centrally, rather than separately for each individual application’s own bespoke step-up implementation.

Multiple Conditions in the Same Sub-Flow

When two or more condition executions sit at the top of the same Conditional sub-flow, they combine using the same Required/Alternative rules that govern any other sibling executions. Two conditions both marked Required means both facts must hold true simultaneously for the sub-flow to proceed; two conditions marked Alternative to each other mean either one being true is sufficient.

Nesting One Conditional Sub-Flow Inside Another

A Conditional sub-flow can itself contain another Conditional sub-flow nested inside it, allowing a genuinely layered decision: “if this user holds the sensitive Role, then further check whether they’ve already enrolled in a hardware key; if so, require it; if not, fall back to requiring OTP instead.” Each layer narrows the population still further before the next condition is even checked.

graph TD
    Outer["Conditional: User Role = finance-approver"]
    Outer --> Inner["Conditional: User Configured = Security Key"]
    Inner -->|"Configured"| Req1["Required: Security Key Check"]
    Inner -->|"Not configured"| Fallback["Required: OTP Form (fallback)"]
    Outer -->|"Role not held"| SkipAll["Entire structure skipped"]
    

An Alternative to Deep Nesting: Multiple Sibling Conditional Sub-Flows

Rather than nesting one Conditional sub-flow deeply inside another, an equally valid and often more readable alternative is placing several Conditional sub-flows as plain siblings at the same level, each with its own distinct, self-contained condition covering one specific population. A flow with three sibling Conditional sub-flows — one for administrators, one for finance staff, one for everyone else — is frequently easier for a reviewer to scan and understand at a glance than the equivalent logic expressed as two or three layers of nesting, even when the two structures produce identical results for every actual user.

Combining Sibling Sub-Flows Correctly

When using the sibling approach, it’s worth double-checking that the populations covered by each sibling Conditional sub-flow are genuinely intended to be mutually exclusive, or, if overlap is possible, that the resulting combined behavior for a user matching more than one is actually the intended outcome. A user who happens to hold both the “administrator” and “finance-approver” Roles, for example, might trigger two separate sibling sub-flows in sequence unless the flow’s design deliberately accounts for that overlap.

Choosing Between Nesting and Sibling Structures in Practice

A useful heuristic for deciding between the two approaches: reach for nesting when the second condition is genuinely dependent on the first already having been true — as in the hardware-key-versus-fallback example earlier in this chapter, where checking enrollment status only makes sense once the Role check has already established that this user belongs to the sensitive population in the first place. Reach for siblings when the conditions are independent of one another and simply happen to apply to overlapping or entirely separate populations within the same overall flow. Defaulting to siblings whenever the relationship between two conditions isn’t clearly hierarchical tends to produce the more maintainable structure over time.

Design. An administrator identifies the specific population or scenario that needs different treatment, and chooses the appropriate condition type (Role, attribute, enrollment status, or authentication level) to express that distinction.

Construction. The Conditional sub-flow is added to a customized copy of the relevant parent flow, following the copy-then-modify pattern covered elsewhere in this series, with the condition execution placed first and the actual authentication steps nested beneath it.

Testing. Because the branch only activates for a specific subset of users, testing needs to deliberately cover both sides: at least one account that satisfies the condition, and at least one that doesn’t, confirming each experiences the intended, different path.

Binding and Rollout. The customized flow is bound to its purpose (such as the Realm’s active Browser flow), and the Conditional logic becomes live for every subsequent matching login.

Ongoing Review. As the underlying Role assignments, attributes, or enrollment patterns shift over time, the condition’s real-world effect should be periodically re-verified, since a condition that made sense when written can quietly stop matching its original intent as the broader population it’s evaluated against changes.

graph LR
    A["Population Identified
(who needs different treatment)"] --> B["Condition Type Chosen
(Role, Attribute, Configured, ACR)"]
    B --> C["Sub-Flow Constructed
(on a copied parent flow)"]
    C --> D["Both Branches Tested
(condition met and not met)"]
    D --> E["Bound to Production"]
    E --> F{"Population or Requirements Shift?"}
    F -->|"Yes"| G["Condition Reviewed and Adjusted"]
    G --> D
    

Documenting Intent Alongside Configuration

Because a condition’s underlying purpose is rarely obvious just from reading its technical configuration months later, maintaining a short, plain-language note alongside each Conditional sub-flow — recorded wherever the organization already tracks its identity configuration decisions — pays for itself the first time someone other than the original author needs to understand or modify it. “This branch enforces a hardware key for the transaction-approver Role, added following the Q2 security review” communicates far more, far faster, than the bare configuration alone ever could.

Retiring a Condition That’s No Longer Needed

Just as a condition is designed and rolled out deliberately, it deserves an equally deliberate retirement when its purpose has run its course — for instance, once a gradual MFA rollout described earlier in this guide reaches full adoption, the “not yet enrolled” branch guiding new users through setup may no longer serve any real population and can be safely simplified away, reducing the flow’s ongoing complexity rather than leaving a permanently dormant branch behind indefinitely.

Taken together, these trade-offs point toward a consistent guiding principle: reach for a Conditional Flow when the underlying distinction between populations is genuine and durable enough to justify the added complexity, and resist the temptation to add a new condition for every minor, one-off exception that arises — each one adds a small, permanent tax on every future review of the flow. Treating Conditional Flows as a deliberate, occasionally-used tool rather than a default reflex for every new requirement keeps this trade-off firmly on the favorable side over the long run.

Verifying a Condition Actually Fires as Intended

Presence of a Conditional sub-flow in the configuration proves nothing about its real-world effect. A condition with subtly incorrect logic — checking the wrong Role name, comparing an attribute against the wrong expected value — can silently never trigger for anyone, leaving the intended control entirely dormant while the organization believes it’s active. Testing with real accounts on both sides of the condition, as described in Chapter 10, is the only reliable way to confirm this.

The Level of Authentication Condition Deserves Extra Scrutiny

Because the ACR/LoA condition trusts a value effectively requested by the application itself, an application with a bug (or a compromised or malicious application) could theoretically request a lower authentication level than a genuinely sensitive action actually warrants. Applications performing highly sensitive actions should be reviewed to confirm they request the appropriate level consistently, rather than assuming the identity layer alone fully compensates for an application-side mistake.

Fail-Safe Design: What Happens When a Condition Check Itself Errors Out

A well-designed Conditional Flow should also account for the less obvious case of the condition check itself failing to evaluate cleanly — for instance, an attribute lookup timing out due to an external synchronization issue described in Chapter 6. Organizations building genuinely security-critical Conditional Flows should confirm, through deliberate testing, which way such an error actually resolves: whether it defaults to skipping the sub-flow (potentially bypassing an intended control) or defaults to treating the condition as unmet in the safer, stricter direction. This is a detail easy to overlook during initial design but important to verify before relying on a condition for a genuinely mandatory control.

Reviewing Conditions Alongside Role and Attribute Governance

Because so many condition types ultimately hinge on Role or attribute assignment, a Conditional Flow’s real security guarantee is only as strong as the governance around who can grant those Roles or set those attributes in the first place. A security review of a Conditional Flow is, in an important sense, incomplete without also reviewing who can assign the “finance-approver” Role it checks, or who can set the attribute it compares — the flow’s logic can be flawless while the underlying assignment process is not.

Building a Simple Dashboard Around a High-Stakes Condition

For a Conditional Flow gating a genuinely high-stakes control — the administrator step-up example from Chapter 5, say — it’s worth the modest extra effort of building a small, dedicated view showing that specific condition’s trigger rate and success rate over time, separate from general login metrics. Because this population is typically small, a dashboard scoped specifically to it makes an anomaly (a sudden drop to zero triggers, or a spike in failures) far easier to notice quickly than if the same signal were buried inside aggregate, Realm-wide login statistics.

Good Patterns

• Gate on stable, administrator-controlled facts: Roles and administrator-managed attributes, never anything a user can self-edit for a security-relevant condition
• Pair enrollment conditions in both directions: the “already configured” and “not yet configured” pattern from Chapter 7 for any gradual rollout
• Keep nesting shallow and documented: two or three deliberate layers, each with a clear, written rationale, rather than accumulated depth nobody can explain
• Test both branches explicitly: maintain at least one test account satisfying, and one account not satisfying, each meaningful condition

Anti-patterns to Avoid