Keycloak Authentication Flows Explained

Keycloak does not hard-code login as one fixed sequence such as “username → password → OTP.”

Instead, Keycloak runs an authentication flow. A flow is an ordered tree of authentication steps called executions, and those steps can be grouped inside subflows.

Each execution or subflow has a requirement such as Required, Alternative, Conditional, or Disabled, which determines how Keycloak evaluates that part of the login.

This guide explains that model on Keycloak 26.7.3 before you change anything. You inspect the built-in browser flow, understand how Required, Alternative, Conditional, and Disabled affect evaluation, map flow bindings to login entry points, and use realm events and authentication logs when debugging login behavior. Custom flow design stays in the dedicated custom-flow tutorial—here the focus is understanding and debugging the tree you already have.

Authentication flow mental model

Think of a flow as a small program Keycloak runs during login:

  OIDC / SAML request
        │
        ▼
  Realm binding picks top-level flow  (e.g. browserFlow → "browser")
        │
        ▼
  Walk executions top to bottom by priority
        │
        ├── REQUIRED step fails  ──► login fails
        ├── ALTERNATIVE succeeds ──► skip sibling alternatives
        ├── CONDITIONAL subflow    ──► run only if conditions pass
        └── DISABLED             ──► skip
        │
        ▼
  Authentication complete → tokens / redirect

A single user-facing login page is often the visible tip of several nested subflows. The Browser flow on Keycloak 26.x includes cookie SSO, optional identity-provider redirect, organization identity-first login, and a forms subflow with username/password plus conditional second factor. Misreading one Alternative sibling as Required is a common source of “OTP never appears” or “SSO stopped working” tickets.

Flows, subflows, and executions

Keycloak stores four related concepts in Authentication → Flows:

List flows in realm golinuxcloud:

export KC_BASE='http://127.0.0.1:8080'
export REALM='golinuxcloud'

ADMIN_TOKEN=$(curl -sS -X POST "${KC_BASE}/realms/master/protocol/openid-connect/token" \
  -d 'grant_type=password' -d 'client_id=admin-cli' \
  -d 'username=admin' -d 'password=ChangeMe!2026' | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

With the admin token set, list every flow alias in the realm:

curl -sS -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "${KC_BASE}/admin/realms/${REALM}/authentication/flows" | \
  python3 -c "import sys,json; [print(f\"{f['alias']:22} builtIn={str(f.get('builtIn')):5} provider={f.get('providerId','')}\") for f in json.load(sys.stdin)]"

Sample output:

browser                builtIn=True  provider=basic-flow
direct grant           builtIn=True  provider=basic-flow
registration           builtIn=True  provider=basic-flow
reset credentials      builtIn=True  provider=basic-flow
clients                builtIn=True  provider=client-flow
first broker login     builtIn=True  provider=basic-flow
docker auth            builtIn=True  provider=basic-flow
browser-lab-copy       builtIn=False provider=basic-flow

Built-in flows ship with Keycloak. You can adjust some requirement values on them, but structural changes belong on a copy such as browser-lab-copy. Priority and nesting live on each flow’s Executions tab—not in this summary list.

Required, Alternative, Conditional, and Disabled

Each execution or subflow row has exactly one requirement. That value is the control knob—not the authenticator name.

Important: Required and Alternative are not two independent groups at the same level. If a level contains a Required execution, Keycloak does not evaluate the Alternative executions at that level.

This is why changing forms from Alternative to Required in the default browser flow can stop the Cookie alternative from providing SSO.

Required vs Alternative (truth table)

At the same nesting level, siblings marked Alternative compete; Required rows must pass when reached.

Conditional subflow (truth table)

A Conditional subflow wraps a condition chain plus real authenticators:

Conditions are not optional hints—they gate the subflow. That is why a user without TOTP never sees an OTP field even when OTP is configured as Alternative inside the conditional branch.

In the default browser flow, the two conditions answer different questions:

• Condition - User Configured — does the user have a second-factor authenticator in this subflow configured, such as OTP?
• Condition - credential — was a configured credential such as a passwordless WebAuthn/passkey already used earlier in this authentication? The default configuration uses this to avoid asking for another factor after passwordless authentication.

How Keycloak evaluates a flow

Evaluation rules that match what you see in the Admin Console:

1. Order — Sort rows by priority (lower number runs earlier). Drag handles in the UI change priority; the API exposes the same value.
2. Level — Indentation is nesting depth. Children run inside a parent subflow before the parent marks itself complete.
3. Alternative group — If the level contains no Required execution, Keycloak evaluates Alternative siblings in priority order until one succeeds.
4. Required chain — Required rows must succeed when evaluated; there is no “skip on failure” within a required authenticator.
5. Conditional gate — For a Conditional subflow, evaluate condition executions first; only if they pass run the subflow’s authenticator steps.
6. Disabled — Never invoked.

  Level 0  [Alternative] Cookie          priority 10
           [Disabled]    Kerberos        priority 20
           [Alternative] IdP Redirector   priority 25
           [Alternative] forms           priority 30
             Level 1  [Required] Username Password Form
                      [Conditional] Browser - Conditional 2FA
                        Level 2  [Required] Condition - user configured
                                   [Required] Condition - credential
                                   [Alternative] OTP Form

When a browser OIDC request arrives, Keycloak loads the realm’s browser binding and walks this tree. No single “if OTP enabled” flag exists outside the flow—the tree is the policy.

Built-in Browser flow walkthrough

Open Authentication → Flows → browser in the Admin Console. Expand forms and Browser - Conditional 2FA so the condition and authenticator rows below are visible. The execution tree matches the API output that follows.

Export the same tree from the Admin REST API:

curl -sS -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "${KC_BASE}/admin/realms/${REALM}/authentication/flows/browser/executions" | \
  python3 -c "
import sys,json
for e in json.load(sys.stdin):
    indent='  '*e.get('level',0)
    print(f\"{indent}[{e.get('requirement'):12}] {e.get('displayName')} (priority={e.get('priority')})\")
"

Sample output:

[ALTERNATIVE ] Cookie (priority=10)
[DISABLED    ] Kerberos (priority=20)
[ALTERNATIVE ] Identity Provider Redirector (priority=25)
[ALTERNATIVE ] Organization (priority=26)
  [CONDITIONAL ] Browser - Conditional Organization (priority=10)
    [REQUIRED    ] Condition - user configured (priority=10)
    [ALTERNATIVE ] Organization Identity-First Login (priority=20)
[ALTERNATIVE ] forms (priority=30)
  [REQUIRED    ] Username Password Form (priority=10)
  [CONDITIONAL ] Browser - Conditional 2FA (priority=20)
    [REQUIRED    ] Condition - user configured (priority=10)
    [REQUIRED    ] Condition - credential (priority=20)
    [ALTERNATIVE ] OTP Form (priority=30)
    [DISABLED    ] WebAuthn Authenticator (priority=40)
    [DISABLED    ] Recovery Authentication Code Form (priority=50)

Password login path

User tokenuser has only a password credential—no OTP. A fresh browser login (prompt=login) walks:

1. Cookie (Alternative) — no usable session for this prompt → not satisfied
2. Kerberos — disabled
3. Identity Provider Redirector — skipped when no default IdP applies
4. Organization subflow — typically skipped when organization login is not configured
5. forms (Alternative) — runs Username Password Form (Required)
6. Browser - Conditional 2FA — Condition - User Configured evaluates false because tokenuser has no configured second-factor credential, so the conditional subflow is skipped

Login completes after password validation. For how sessions and cookies relate to later requests, see Keycloak sessions explained.

Cookie SSO shortcut

A second OIDC request without prompt=login, in the same browser context, hits Cookie first:

1. Cookie (Alternative) — existing KEYCLOAK_SESSION satisfies the step
2. Remaining level-0 alternatives, including forms, are skipped
3. Keycloak issues the authorization code without showing the username form

That is the intended SSO behavior—not a bypass bug. If SSO breaks after a flow edit, check whether Cookie was disabled or moved below a failing execution.

Flow bindings and entry points

A flow binding tells Keycloak which top-level authentication flow to use for a particular kind of authentication request.

For example, browserFlow = browser means that browser-based login starts with the flow named browser.

Each Keycloak realm stores binding aliases separately from the flow definitions. Realm bindings on golinuxcloud:

curl -sS -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "${KC_BASE}/admin/realms/${REALM}" | python3 -c "
import sys,json
r=json.load(sys.stdin)
for k in ['browserFlow','registrationFlow','directGrantFlow','resetCredentialsFlow','clientAuthenticationFlow','dockerAuthenticationFlow','firstBrokerLoginFlow']:
    print(f'{k:28} {r.get(k)}')
"

Sample output:

browserFlow                  browser
registrationFlow             registration
directGrantFlow              direct grant
resetCredentialsFlow         reset credentials
clientAuthenticationFlow     clients
dockerAuthenticationFlow     docker auth
firstBrokerLoginFlow         first broker login

The Flows list shows bindings in the Used by column—a green check means the flow is bound. Copied flows such as browser-lab-copy show Not in use until you point a binding at them.

Clients can override the browser binding under Advanced → Authentication flow overrides when one application needs a different tree; the realm binding remains the default for everyone else. Client capability flags (Standard flow, Direct access grants) still gate whether an entry point is reachable—see Keycloak clients explained.

Direct grant contrast

Password grant at the token endpoint uses a separate, flatter flow bound as directGrantFlow. Export its executions the same way:

curl -sS -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "${KC_BASE}/admin/realms/${REALM}/authentication/flows/direct%20grant/executions" | \
  python3 -c "
import sys,json
for e in json.load(sys.stdin):
    indent='  '*e.get('level',0)
    print(f\"{indent}[{e.get('requirement'):12}] {e.get('displayName')} (priority={e.get('priority')})\")
"

Sample output:

[REQUIRED    ] Username Validation (priority=10)
[REQUIRED    ] Password (priority=20)
[CONDITIONAL ] Direct Grant - Conditional OTP (priority=30)
  [REQUIRED    ] Condition - user configured (priority=10)
  [REQUIRED    ] OTP (priority=20)

Same requirement semantics, different entry point. Changing browser does not change direct grant—a common mistake when teams disable password grant in the client but leave directGrantFlow untouched at the realm level.

Safely test a copied flow

Keycloak ships built-in authentication flows such as browser. You can change some execution requirements on a built-in flow, but structural customization should be done on a copy.

For anything beyond a small requirement change, duplicate the flow first. That gives you a separate tree that you can add to, reorder, test, and roll back without redesigning the built-in flow.

Copy the built-in browser flow:

curl -sS -o /dev/null -w 'copy-flow:%{http_code}\n' -X POST \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H 'Content-Type: application/json' \
  "${KC_BASE}/admin/realms/${REALM}/authentication/flows/browser/copy" \
  -d '{"newName":"browser-lab-copy"}'

HTTP 201 creates browser-lab-copy with builtIn=false. Confirm the copy is editable and not built-in:

curl -sS -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "${KC_BASE}/admin/realms/${REALM}/authentication/flows" | \
  python3 -c "import sys,json; f=[x for x in json.load(sys.stdin) if x['alias']=='browser-lab-copy'][0]; print('builtIn=', f.get('builtIn'))"

builtIn= False

Bind the copy at the realm only when you are ready to test—then revert:

curl -sS "${KC_BASE}/admin/realms/${REALM}" -H "Authorization: Bearer ${ADMIN_TOKEN}" > /tmp/realm.json

Point browserFlow at the copy in a throwaway JSON file:

python3 -c "
import json
with open('/tmp/realm.json') as f: r=json.load(f)
r['browserFlow']='browser-lab-copy'
with open('/tmp/realm-bind.json','w') as f: json.dump(r,f)
"

Push the binding change to the realm:

curl -sS -o /dev/null -w 'bind-copy:%{http_code}\n' -X PUT \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H 'Content-Type: application/json' \
  -d @/tmp/realm-bind.json "${KC_BASE}/admin/realms/${REALM}"

Restore the default binding immediately after your test. Reset browserFlow in JSON first:

python3 -c "
import json
with open('/tmp/realm.json') as f: r=json.load(f)
r['browserFlow']='browser'
with open('/tmp/realm-restore.json','w') as f: json.dump(r,f)
"

Apply the restore payload:

curl -sS -o /dev/null -w 'restore-browser:%{http_code}\n' -X PUT \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H 'Content-Type: application/json' \
  -d @/tmp/realm-restore.json "${KC_BASE}/admin/realms/${REALM}"

Step-by-step customization (adding executions, OTP policies, publishing to production) belongs in Create a custom Keycloak authentication flow—this section stops at copy, bind, and rollback.

Debug with events and logs

Before editing requirements, record what the default flow actually did. Enable realm events once per lab:

python3 -c "
import json
with open('/tmp/realm.json') as f: r=json.load(f)
r['eventsEnabled']=True
r['adminEventsEnabled']=True
types=set(r.get('enabledEventTypes') or [])
types.update(['LOGIN','LOGIN_ERROR'])
r['enabledEventTypes']=sorted(types)
with open('/tmp/realm-events.json','w') as f: json.dump(r,f)
"

Upload the updated realm configuration:

curl -sS -o /dev/null -w 'enable-events:%{http_code}\n' -X PUT \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H 'Content-Type: application/json' \
  -d @/tmp/realm-events.json "${KC_BASE}/admin/realms/${REALM}"

Run a browser login against client pkce-lab-spa, then query recent LOGIN events:

curl -sS -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  "${KC_BASE}/admin/realms/${REALM}/events?type=LOGIN&max=3" | python3 -c "
import sys,json,datetime
for e in json.load(sys.stdin):
    ts=datetime.datetime.fromtimestamp(e['time']/1000).strftime('%Y-%m-%d %H:%M:%S')
    d=e.get('details',{})
    print(f\"{ts}  client={e.get('clientId')}  user={d.get('username')}  auth_type={d.get('auth_type')}\")
"

Sample output:

2026-09-24 23:45:25  client=pkce-lab-spa  user=tokenuser  auth_type=code
2026-09-24 23:45:20  client=pkce-lab-spa  user=tokenuser  auth_type=code

Events confirm login outcomes; they do not list individual execution names such as Cookie → forms → OTP Form. For execution-level detail, temporarily raise org.keycloak.authentication log level in start-dev, reproduce once, and grep container logs—or use the tree walkthrough above to predict the path before you change a requirement.

Admin events record structural changes such as flow copies. After the browser/copy call above, Admin events shows an operation like CREATE AUTH_FLOW authentication/flows/browser/copy.

Use Events → Admin events in the console when you need to know who rebound browserFlow during an incident.

Common flow design mistakes

Summary

Keycloak authentication is flow-driven: realm bindings pick which tree runs for browser login, direct grant, registration, and other entry points. Each tree is an ordered list of executions and subflows with Required, Alternative, Conditional, or Disabled requirements that govern evaluation order and success.

On Keycloak 26.7.3, the default browser flow explains everyday behavior—Cookie short-circuits to SSO, forms collects username and password, and Browser - Conditional 2FA adds OTP only when Condition - User Configured and the other conditions inside that subflow pass. Alternative siblings are evaluated only when the level contains no Required execution; Conditional subflows gate entire branches; Disabled rows disappear from the path entirely.

Inspect the built-in tree, use LOGIN events for login outcomes and authentication logs for execution-level detail, duplicate into browser-lab-copy before structural changes, and revert browserFlow to browser if a binding experiment fails. When you need a production custom tree, continue with the custom authentication flow guide—carrying the requirement semantics from this page with you.

References

• Keycloak Server Administration Guide — Authentication flows
• Keycloak Server Administration Guide — Configuring authentication
• Keycloak Admin REST API — Authentication management