What Is the Browser Flow in Keycloak?
The default sequence of checks — silent, familiar, or entirely custom — that decides exactly what happens the moment someone tries to log in through a browser.
Every time a user’s browser is redirected to Keycloak’s login page, something is quietly deciding what happens next: should an existing session be silently reused? Should the user be bounced to an external identity provider? Should a password form appear, followed by an MFA prompt? That decision-making sequence is called the Browser Flow, and it’s arguably the single most important piece of configuration in a Keycloak realm — because it governs the very first experience nearly every human user has with the system. This guide takes an in-depth look at what the Browser Flow actually is, what it’s made of, how it executes step by step, and how to customize it thoughtfully and safely.
ACore Concepts: What Exactly Is the Browser Flow?
In Keycloak, an Authentication Flow is a named, ordered sequence of steps — called Executions — that a login attempt must pass through before Keycloak considers a user authenticated. Keycloak doesn’t hardcode a single fixed login process; instead, it ships with several pre-built flows for different situations, and the Browser Flow is specifically the one used whenever a user authenticates through a standard web browser, as opposed to, say, a backend service authenticating via the Direct Grant flow.
Think of the Browser Flow like the sequence of checkpoints at an airport before boarding a flight. There’s a specific order: check-in, security screening, passport control, gate boarding — and at some checkpoints, you might be waved straight through if you already hold valid pre-cleared status (like an existing session cookie), while at others you must stop and complete a required step. The Browser Flow is Keycloak’s version of that airport checkpoint sequence, purpose-built for the moment a human sits down at a browser and tries to log in.
What makes the Browser Flow especially powerful is that it isn’t a black box — every checkpoint inside it is visible, configurable, and reorderable through the Keycloak Admin Console’s Authentication section. Administrators can see the exact sequence of executions, add new ones (like an OTP step), remove ones they don’t need, and adjust each execution’s requirement level to control whether it must pass, is merely one of several acceptable alternatives, or only applies under certain conditions.
The Browser Flow is just one of several Authentication Flows Keycloak maintains. Others include the Direct Grant Flow (for username/password login via a direct API call, with no browser redirect), the Registration Flow (for new account sign-up), the Reset Credentials Flow (for “forgot password” journeys), and the First Broker Login Flow (for the very first login via an external identity provider). This guide focuses specifically on the Browser Flow.
Where the Browser Flow Is Configured
Within the Admin Console, the Browser Flow lives under the realm’s Authentication section, listed alongside the other built-in flows. A separate Bindings tab is where an administrator specifies which flow is actually used for which purpose realm-wide — for example, designating a specific flow (the default Browser Flow, or a customized copy of it) as the realm’s active “Browser Flow” binding.
Why the Browser Flow Deserves Special Attention
Because it’s the entry point for essentially every human user of every connected application, changes to the Browser Flow have realm-wide impact — a misconfiguration here can lock out every user, accidentally weaken security across the board, or introduce confusing, inconsistent login experiences. Understanding its structure deeply before making changes is genuinely important, not just academically interesting.
BArchitecture & Core Components
flowchart TB
Start["Login Request Arrives"] --> Cookie["Cookie Check"]
Cookie -->|"valid session found"| Skip["Skip straight to token issuance"]
Cookie -->|"no valid session"| Kerberos["Kerberos (disabled by default)"]
Kerberos --> IdPRedirect["Identity Provider Redirector"]
IdPRedirect -->|"configured to redirect"| ExternalIdP["External Identity Provider"]
IdPRedirect -->|"no redirect configured"| Forms["Forms Sub-Flow"]
Forms --> UPForm["Username Password Form (Required)"]
UPForm --> OTP["Conditional OTP Form"]
OTP --> IssueTokens["Resolve Session + Issue Tokens"]
Let’s unpack each of these components individually.
Cookie
The very first execution checked. If the browser presents a valid session cookie linked to an existing, still-active User Session, Keycloak can skip the rest of the flow entirely and proceed straight to issuing fresh tokens — this is the specific mechanism that makes Single Sign-On feel instantaneous for a second or third connected application.
Kerberos
An optional execution, disabled by default, that supports desktop Single Sign-On in environments using Kerberos-based authentication (common in some enterprise Windows domain setups) — allowing a user already authenticated at the operating-system level to be recognized by Keycloak without any additional login step.
Identity Provider Redirector
A step that checks whether the realm is configured to automatically redirect users to an external Identity Provider (like a partner company’s own IdP, or a social login provider) rather than showing Keycloak’s own login form — useful for realms where every login is expected to go through one specific external source.
Forms (a Sub-Flow)
Rather than being a single execution, “Forms” is itself a sub-flow — a nested flow containing its own sequence of executions. This is where the actual username/password login experience, and any additional factors layered on top of it, are defined.
Username Password Form
Nested inside the Forms sub-flow, this is the execution responsible for rendering the login form and checking submitted credentials, as covered in depth in an earlier guide on Username/Password Authentication.
Conditional OTP Form (or Other MFA Steps)
Commonly added as the next step after the password form, this execution can be configured to require a one-time password only under certain conditions — for example, only for users in a specific group, or only if the user has already enrolled an OTP credential — giving administrators fine control over exactly who faces the extra step.
People sometimes assume the Browser Flow is a single, fixed sequence that can’t meaningfully change. In reality, every execution shown above can be reordered, replaced, or removed, and entirely new executions — additional MFA methods, risk-based conditional steps, custom authenticators — can be inserted anywhere in the sequence.
CHow the Browser Flow Executes Internally
The Four Requirement Levels
Every execution and sub-flow within an Authentication Flow is assigned one of four requirement levels, and understanding these precisely is the key to understanding how the whole flow actually behaves:
Must Succeed
This execution must complete successfully for the overall flow to proceed — if it fails, the entire login attempt fails.
One of Several Options
Among a group of Alternative executions at the same level, only one needs to succeed for the flow to proceed past that point.
Runs Based on a Condition
A sub-flow that only actually executes its contents if a configured condition (like group membership or a user attribute) evaluates true.
Skipped Entirely
The execution is configured but not active — present in the flow’s definition but effectively bypassed during real logins.
Top-to-Bottom Evaluation Order
Keycloak evaluates executions within a flow (or sub-flow) in the order they’re listed in the Admin Console, from top to bottom. This ordering genuinely matters — for example, placing the Cookie check before the Forms sub-flow is exactly what allows an existing session to bypass the login form entirely, rather than forcing a redundant re-login every time.
Think of a restaurant’s fixed-price menu with a required appetizer, a choice between two alternative mains, and an optional dessert only offered to members of the loyalty program. The Required appetizer is non-negotiable. The Alternative mains mean picking either one satisfies that course. The Conditional dessert only appears at all for a specific group of diners. And a Disabled item is simply crossed off the menu entirely, even though it’s still printed in the master recipe book.
Sub-Flows and Nesting
A sub-flow (like “Forms”) is itself treated as a single execution from the perspective of its parent flow — the parent only cares whether the sub-flow, as a whole, succeeded or failed, while the sub-flow internally manages its own nested sequence of Required, Alternative, and Conditional executions.
Authenticator Configuration
Many individual executions carry their own specific configuration, accessible via a small settings icon next to each one in the Admin Console — for example, the Conditional OTP execution’s configuration is exactly where an administrator defines which group or attribute triggers the condition.
A common, safe practice is to duplicate the built-in Browser Flow before making any changes, then bind the realm to the new, customized copy rather than editing the original directly. This keeps a known-good fallback available if a customization introduces unexpected behavior.
DData Flow & the Login Journey Through the Browser Flow
flowchart LR
A["1. User's browser redirected to Keycloak"] --> B["2. Cookie execution checks for valid session"]
B -->|"valid"| G["7. Tokens issued immediately"]
B -->|"none"| C["3. Kerberos check (usually skipped)"]
C --> D["4. Identity Provider Redirector check"]
D -->|"redirect configured"| ExtIdP["Redirect to external IdP"]
D -->|"no redirect"| E["5. Forms sub-flow: Username Password Form"]
E --> F["6. Conditional OTP Form, if applicable"]
F --> G
Redirect to Keycloak
An application redirects the user’s browser to Keycloak’s authorization endpoint, initiating the Browser Flow for that realm.
Cookie Check
Keycloak checks for a valid existing session cookie. If found and still valid, most of the remaining flow can be bypassed entirely.
Kerberos and Identity Provider Checks
If no valid session exists, Keycloak checks whether Kerberos desktop SSO applies, and whether the realm is configured to redirect straight to an external Identity Provider.
Forms Sub-Flow Begins
Assuming no earlier step resolved the login, the Forms sub-flow takes over, starting with the Username Password Form.
Credential Verification
The user’s submitted username and password are checked, as detailed in the dedicated Username/Password Authentication guide.
Conditional Second Factor
If configured and applicable to this specific user, an OTP or other MFA step follows, adding a second layer of verification.
Session and Token Issuance
Once every Required execution in the flow has succeeded, Keycloak creates or updates the User Session and issues tokens back to the requesting application.
EAdvantages, Disadvantages & Trade-offs
Advantages
- Every step in the login journey is visible, reorderable, and independently configurable through the Admin Console.
- Conditional logic allows different users to face different requirements — like MFA only for privileged groups — without custom code.
- The Cookie-first ordering enables genuinely seamless Single Sign-On across every connected application.
- Sub-flows keep complex logic organized and modular, rather than one enormous flat sequence of steps.
- Realm-wide binding means one well-designed flow consistently governs login for every connected application.
Disadvantages / Trade-offs
- Misconfiguring requirement levels can accidentally weaken security (an important step wrongly set to Alternative) or lock everyone out (a broken step wrongly set to Required).
- Complex nested sub-flows with many conditions can become difficult to reason about at a glance.
- Because it applies realm-wide by default, a single change affects every connected application unless explicitly overridden per Client.
- Testing every conditional branch thoroughly requires deliberate effort, since some paths only trigger for specific user segments.
A fully custom security checkpoint process at a corporate headquarters — with different rules for visitors, contractors, and employees — offers precise, tailored control. But designing it well takes real thought, and a mistake in the rules (like accidentally requiring every visitor to have an employee badge) can bring the entire building’s foot traffic to a halt.
FSecurity Considerations
Never Weaken the Password Step Without a Strong Alternative
If the Username Password Form’s requirement level is loosened, or reordered relative to other steps, without a genuinely equivalent alternative in place, it can accidentally weaken the overall strength of the login process realm-wide.
Layer MFA Deliberately, Not Accidentally
Conditional OTP (or other MFA) executions should be configured with clear, deliberate logic about who they apply to — an overly narrow condition might leave sensitive accounts under-protected, while an overly broad one might create unnecessary friction for low-risk logins.
Editing the realm’s actively bound Browser Flow directly, without first duplicating it, means any mistake immediately affects every user attempting to log in — including administrators trying to fix the very mistake they just made. Always test changes on a duplicated flow before switching the realm’s binding over to it.
Review Identity Provider Redirector Configuration Carefully
If the Identity Provider Redirector is configured to automatically send users to an external IdP, it’s worth confirming that trust relationship is genuinely intended and well understood — an unintentional or overly broad redirect configuration could send users somewhere unexpected.
Audit Flow Changes Through Admin Events
Because Authentication Flow modifications are exactly the kind of high-impact configuration change worth tracking, ensuring Admin Events capture changes to Authentication Flows (as covered in the Events Logging guide) gives administrators a clear audit trail of who changed the login process and when.
The Idea
Use a Conditional sub-flow to require stronger authentication (like OTP or WebAuthn) specifically for privileged roles or risk-flagged logins, while keeping the experience lighter for low-risk, ordinary users.
Why It Matters
This applies stronger protection exactly where the consequences of compromise are highest, without imposing unnecessary friction across the entire user base uniformly.
GMonitoring, Logging & Metrics
Tracking Login Success and Failure Rates
Monitoring the ratio of successful to failed logins through Events Logging can surface both user-experience issues (a confusing new MFA step causing widespread failures) and potential attack activity (an unusual spike in failed password attempts).
Measuring Time-to-Login
Tracking how long, on average, a login attempt takes to complete through the flow can highlight steps that introduce unexpected latency — such as a federated LDAP check taking longer than anticipated under real production load.
Monitoring Conditional Branch Usage
For flows with conditional MFA steps, it’s useful to track how often each branch actually triggers — confirming that a condition intended to apply to a specific group is, in practice, matching exactly the population it was designed for, and not accidentally over- or under-including users.
Tracking how often logins are resolved purely by the Cookie execution (silent SSO) versus requiring a full password prompt gives a useful signal about session timeout tuning — an unexpectedly low silent-SSO rate might indicate an Idle timeout configured too aggressively for how users actually navigate between applications.
Alerting on Flow Configuration Changes
Because Browser Flow changes are high-impact by nature, configuring alerts on Admin Events specifically related to Authentication Flow modifications helps ensure such changes are always reviewed and intentional, never accidental or unnoticed.
HDesign Patterns & Anti-Patterns
Good Pattern: Duplicate Before Customizing
Always work from a duplicated copy of the built-in Browser Flow, keeping the original untouched as a reliable fallback and clear reference point for what “default” behavior looks like.
Good Pattern: Use Conditional Sub-Flows for Segmented Requirements
Rather than building entirely separate flows for different user populations, use Conditional sub-flows within one well-organized Browser Flow to apply different requirements (like MFA) to different segments based on group, role, or attribute.
Good Pattern: Override Per-Client Only When Genuinely Needed
Keycloak allows individual Clients to override the realm’s default flow binding for special cases — use this sparingly and deliberately, since scattered per-Client overrides can make the overall login behavior harder to reason about across the whole realm.
What It Looks Like
Making experimental changes directly to the Browser Flow currently bound and actively used by the realm, rather than testing on a duplicate first.
Why It’s a Problem
Any mistake immediately impacts every user attempting to log in, with no safe fallback readily available — a particularly painful failure mode given how central this flow is to the entire system’s usability.
What It Looks Like
Accumulating many layered Conditional sub-flows over time, each addressing a specific edge case, with no documentation explaining the overall intended logic.
Why It’s a Problem
It becomes nearly impossible for anyone other than the original author to confidently predict what a given user will experience, making future changes risky and troubleshooting genuinely difficult.
IBest Practices & Common Mistakes
Test Every Conditional Branch
Explicitly verify the login experience for every distinct user segment a conditional step is designed to treat differently.
Document the Flow’s Intended Logic
Keep a clear, current written explanation of why each customization exists, so future administrators understand the reasoning, not just the configuration.
Review Requirement Levels After Any Change
Double-check that Required, Alternative, and Conditional assignments still reflect the intended security posture after every modification.
Keep a Rollback Plan Ready
Know exactly how to revert the realm’s flow binding back to a known-good flow quickly if a change causes unexpected login problems.
Common Mistakes to Avoid
- Forgetting the Cookie step’s importance: Removing or misordering it can unintentionally break Single Sign-On, forcing repeated logins across connected applications.
- Setting a broken custom execution to Required: A misconfigured or buggy custom step marked Required can lock out every user until it’s fixed.
- Not testing the Kerberos or Identity Provider Redirector paths: If enabled, these steps deserve the same testing rigor as the primary password path, since they affect real login attempts too.
- Applying changes realm-wide when only one application needed them: Consider a per-Client flow override instead of altering the shared realm-wide Browser Flow for a need specific to just one application.
JReal-World & Industry Examples
Enterprise Realm: Mandatory MFA for Administrators Only
A large organization commonly configures a Conditional OTP step that only triggers for users belonging to an “administrators” group, keeping the login experience simple for ordinary employees while enforcing a strong second factor for the accounts with the most sensitive access.
Enterprise Realm: Kerberos Desktop SSO
An organization running a traditional Windows domain environment might enable the Kerberos execution, allowing employees already authenticated at their workstation to be recognized by Keycloak automatically, without any additional login form appearing at all.
SaaS Platform: Forced Redirect to a Partner’s IdP
A business-to-business SaaS platform serving one large enterprise client might configure the Identity Provider Redirector to automatically send that client’s users straight to their own corporate identity provider, skipping Keycloak’s native login form for that specific population entirely.
Customer Platform: Risk-Based Conditional Step
A consumer-facing platform might add a custom conditional execution that only requires additional verification when a login originates from an unfamiliar device or location, balancing security with a smooth experience for genuinely low-risk, familiar logins.
KFrequently Asked Questions
LSummary & Key Takeaways
Key Takeaways
- The Browser Flow is Keycloak’s default, fully configurable Authentication Flow used whenever a user logs in through a standard web browser.
- It’s built from an ordered sequence of Executions — including Cookie, Kerberos, Identity Provider Redirector, and a nested Forms sub-flow — each assigned a specific requirement level.
- The four requirement levels — Required, Alternative, Conditional, and Disabled — precisely govern how each step behaves and whether it applies to a given login.
- The Cookie execution, checked first, is exactly what enables seamless Single Sign-On across connected applications.
- Conditional sub-flows let administrators apply different requirements — like MFA — to different user segments without custom application code.
- Because it governs login for essentially every human user, changes should always be tested on a duplicated flow, with careful attention to requirement levels, before being bound to the live realm.
- Well-designed customizations remain documented, deliberately scoped, and periodically reviewed as the organization’s security needs evolve.