What is Step-Up Authentication in Keycloak?
Not every action deserves the same level of scrutiny at the door. Step-up authentication is how Keycloak asks for a stronger form of proof exactly when — and only when — the stakes actually justify it.
Imagine an office building where the front lobby only requires a swipe of your badge, but the server room deep inside requires that same badge plus a fingerprint scan on top. Nobody expects the fingerprint reader at the front door — that would slow everyone down for no good reason — but nobody would want the server room protected by nothing more than the same badge that gets you past the lobby either. Step-Up Authentication is Keycloak’s version of this layered building: it lets a user log in normally with a lighter-weight method for everyday access, and then, only when they try to reach something more sensitive, prompts them for a stronger, additional proof of identity — without forcing everyone to carry that extra burden for every single action, all the time. This guide, written for a technical audience with some familiarity with identity systems, walks through what step-up authentication actually is, the standards and claims underneath it, how Keycloak implements it architecturally, what happens internally on every request, and how real organizations design, secure, and operate it at scale. No prior background in adaptive or risk-based authentication is assumed, though comfort with core identity concepts like tokens and authentication flows will help.
1Core Concepts
The problem with a single, uniform login bar
Most systems, by default, apply exactly one login requirement to every user for every action, once they’re authenticated. A user who logged in with just a password an hour ago is treated as equally trusted for reading a public dashboard as they are for wiring a large sum of money or deleting a customer’s entire account. This uniform approach forces an uncomfortable choice: either set the login bar high enough to protect the most sensitive actions — annoying users for every trivial task — or set it low enough for convenience, leaving sensitive actions under-protected. Step-up authentication exists specifically to escape this false choice.
What does “stepping up” actually mean?
Step-Up Authentication is the practice of requiring a user, who is already authenticated at some baseline level, to provide an additional or stronger form of proof before being allowed to proceed with a specific, more sensitive action. The user isn’t asked to fully log out and back in — their existing session remains intact — but a targeted, incremental authentication challenge is inserted right before the sensitive action is permitted, and only for that action.
Think of an amusement park where a general admission wristband lets you walk around, visit the shops, and ride the gentle rides freely. But at the entrance to the roller coaster, an attendant checks your height against a marked bar — an extra, specific check applied only at that one gate, for that one activity, without requiring everyone to clear that bar just to enter the park in the first place. Step-up authentication works the same way: your general session gets you around the application, but specific “rides” — sensitive actions — have their own extra check at the gate.
Why can’t Keycloak’s normal login just always be “strong enough”?
Setting a uniformly strong authentication requirement for every single login sounds appealing until you consider the real cost: users log in far more often than they perform genuinely sensitive actions. Forcing a hardware security key check, for instance, on every single login — including just checking a public status page — creates friction disproportionate to the actual risk of that specific action. Step-up authentication lets an application match authentication strength to actual risk, action by action, rather than uniformly across every single interaction a user has.
A banking application that lets a user check their balance with a normal login but demands a fingerprint or hardware key before approving a wire transfer, an admin console that requires extra verification before a destructive delete action, or a healthcare system requiring stronger proof before viewing the most sensitive category of patient records are all natural homes for step-up authentication.
Key vocabulary, explained simply
Authentication Context
A description of how strongly a user’s identity was actually verified during a given login — which methods were used, and how confident the result is.
Baseline Authentication
The initial, typically lighter-weight login method a user completes to establish their session in the first place.
Step-Up Challenge
The additional authentication prompt inserted before a specific, more sensitive action, without disturbing the user’s overall session.
Sensitive Action
Any operation an application designates as warranting extra scrutiny — a large transaction, a destructive change, access to especially protected data.
Authentication Flow
Keycloak’s configurable sequence of steps a login must pass through, which step-up authentication extends conditionally for specific scenarios.
Re-authentication
The general term for prompting a user to prove their identity again after their session has already begun, which step-up authentication applies selectively and purposefully.
2Standards, Claims & Protocol Foundations
The Authentication Context Class Reference (ACR)
OpenID Connect defines a claim called acr — the Authentication Context Class Reference — a value included in an issued token describing, in a standardized way, how the user was actually authenticated for that specific login. An application, or a token consumer, can look at this claim and know, without ambiguity, whether the user proved their identity with just a password, or with a password plus a second factor, or with an especially strong method like a hardware security key. Keycloak issues this claim as part of its tokens, and it’s the foundation step-up authentication is built directly on top of.
The Authentication Methods Reference (AMR)
A closely related claim, amr — the Authentication Methods Reference — lists the specific methods actually used during authentication, such as a password, a one-time code, or a WebAuthn assertion. Where acr expresses an overall strength level, amr gives the finer-grained detail of exactly which methods contributed to reaching that level. Together, these two claims let an application ask two related but distinct questions: “how strong was this login, overall?” and “specifically, how was it done?”
Think of a food safety inspection certificate. The acr claim is like the overall letter grade posted in the restaurant’s window — a quick, standardized summary of how the inspection went. The amr claim is like the detailed inspection report behind that grade, listing exactly which specific checks were performed to arrive at it. A restaurant patron glancing at the window mostly cares about the letter grade; a health inspector reviewing a complaint cares about the detailed report behind it.
Requesting a specific authentication strength
Because acr is a standardized claim, an application (or Keycloak itself, acting on an application’s behalf during a step-up flow) can also make a request for a specific authentication context to be satisfied — effectively saying, “before I let you through, I need proof that reaches at least this level of strength.” If the user’s existing session already satisfies that requested level, no further prompt is needed at all. If it doesn’t, this is precisely the moment a step-up challenge is triggered.
The specific string values used for acr levels aren’t universally fixed by the standard itself — they’re defined by the identity provider (in this case, Keycloak, through its configured authentication flows), meaning the exact meaning of “level 2” or a named authentication context is deployment-specific and must be documented clearly for any application relying on it.
Why building on a standard matters
Relying on these standardized OpenID Connect claims, rather than a proprietary, Keycloak-only mechanism, means applications can reason about authentication strength using well-understood, portable concepts, and that the underlying protocol interactions (requesting a specific context, receiving confirmation of what was actually achieved) follow patterns any OpenID Connect-literate developer can recognize, even before learning Keycloak’s specific configuration details.
acr claim
Describes the overall strength level actually achieved during authentication, included in the issued token.
amr claim
Lists the specific methods used to achieve that strength, offering finer detail than the level alone.
acr_values request parameter
Used by a client to request a specific minimum authentication context be satisfied, either at initial login or via a step-up re-authentication.
Conditional Authentication Flow
Keycloak’s mechanism for defining what actually needs to happen to satisfy a given requested context, configured per realm.
3Architecture & Components
graph TB
APP[Application] -->|detects sensitive action| CHK{Session's acr
meets requirement?}
CHK -->|yes| ALLOW[Proceed with action]
CHK -->|no| REDIR[Redirect to Keycloak
with acr_values requested]
REDIR --> AF[Conditional
Authentication Flow]
AF --> STRONG[Stronger Authenticator
e.g. WebAuthn, OTP]
STRONG --> NEWTOK[New Token with
updated acr claim]
NEWTOK --> APP
Component breakdown
Conditional Authentication Flow
A Keycloak authentication flow configured with conditions and executions that determine what a user must additionally complete to satisfy a specific requested authentication context.
Application-Side Sensitivity Detection
The application’s own logic identifying which specific actions warrant a step-up request, and issuing the appropriate re-authentication request to Keycloak when needed.
acr_values Request Handling
Keycloak’s logic for interpreting an incoming request for a specific authentication context and routing the user through whatever flow satisfies it.
Token Claim Population
The part of Keycloak’s token issuance responsible for correctly reflecting the actually-achieved authentication context in the resulting token’s acr and amr claims.
Where this is configured in the admin console
Inside the Keycloak Admin Console, step-up authentication is built by creating or customizing an Authentication Flow under the realm’s Authentication section, adding conditional executions that check the requested authentication context and branch accordingly — for example, requiring an additional OTP or WebAuthn step only when a higher context level has been specifically requested.
A common real setup
A financial application configures its normal login flow to satisfy a baseline authentication context using just a password. Separately, a conditional flow is set up so that when a request specifically asks for a higher context level — triggered by the application right before a large transaction — the user is additionally required to complete a WebAuthn challenge, with the resulting token reflecting this stronger context so the application can confirm it was genuinely satisfied before proceeding.
Why does the application, not just Keycloak, need its own logic here?
Keycloak’s job is to handle the mechanics of authentication — presenting the right challenge and issuing a token reflecting what was achieved. But deciding which specific actions actually warrant a step-up is inherently an application-level, business-context decision: only the application genuinely knows that “approve this transfer” is sensitive while “view this dashboard” is not. This is why a complete step-up implementation always involves cooperation between Keycloak’s authentication machinery and deliberate, explicit logic within the application itself.
4Internal Working
How a step-up request is recognized and routed
When an application redirects a user back to Keycloak specifically requesting a higher authentication context — typically via the standard acr_values parameter — Keycloak’s authentication flow engine evaluates the user’s current session against what’s being requested. If the session already satisfies the requested level (perhaps the user recently completed a strong login for an unrelated reason), Keycloak can silently confirm this without prompting the user at all. If it doesn’t, Keycloak routes the user through whichever conditional flow steps are configured to satisfy that specific, higher context.
Ensuring the token honestly reflects what happened
Once the step-up challenge is completed, Keycloak issues a new token (or updates the existing session’s reflected context) with an acr claim value accurately representing the strength actually achieved — not merely what was requested. This distinction matters: a well-implemented application should always verify the acr claim actually returned in the token, rather than simply trusting that because it requested a high level, a high level was necessarily delivered — a request can, in some configurations, fail to be fully satisfied, and honest claim population is what lets the application detect this.
Session-level versus request-level step-up
There are two general patterns for how long a completed step-up “counts.” In a session-level approach, once a user successfully completes a step-up challenge, their entire session is upgraded, and no further step-up is needed for subsequent sensitive actions during that session. In a more conservative, request-level approach, a step-up might only be considered valid for a short window or a single specific action, requiring the user to step up again for a second, similarly sensitive action shortly afterward. Which pattern is appropriate depends heavily on the specific risk profile of the actions involved.
A session-level step-up that never expires or re-checks can quietly become a permanent elevation — if a user steps up once early in a long session, and that elevation is never re-verified, a stolen or hijacked session later in that same lifetime could exploit a stale, previously legitimate step-up without ever proving the stronger factor again.
Step-by-step: a full step-up authentication cycle
User attempts a sensitive action
The application’s own logic recognizes this action requires a stronger authentication context than the user’s current session provides.
Re-authentication request issued
The application redirects the user to Keycloak, specifically requesting the required authentication context.
Keycloak evaluates current session
If the session already satisfies the request, Keycloak can proceed without prompting; otherwise, it identifies what’s needed.
Stronger challenge presented
The user completes whatever additional authenticator (a hardware key, an OTP, a fresh password entry) the conditional flow requires.
Token issued reflecting the new context
A token with an updated acr claim, honestly reflecting the strength actually achieved, is returned.
Application verifies and proceeds
The application checks the returned claim actually meets its requirement before finally allowing the sensitive action.
5Data Flow & Lifecycle
sequenceDiagram
participant User
participant App as Application
participant Keycloak
User->>App: Requests sensitive action (e.g. large transfer)
App->>App: Checks current session's acr claim
App->>Keycloak: Redirects with acr_values=strong-mfa
Keycloak->>Keycloak: Compares against current session context
alt Already sufficient
Keycloak-->>App: Confirms context, no prompt shown
else Insufficient
Keycloak->>User: Presents step-up challenge (e.g. WebAuthn)
User->>Keycloak: Completes challenge
Keycloak-->>App: Issues token with upgraded acr claim
end
App->>App: Verifies returned acr meets requirement
App->>User: Proceeds with sensitive action
Notice the branch in that diagram: step-up authentication is not always visible to the user. When their existing session already satisfies the required context — perhaps because they recently completed a strong login for some other reason — Keycloak can confirm this silently, without any additional prompt at all. The user only ever sees an extra challenge when their current session genuinely falls short of what’s required, which is exactly the targeted, minimal-friction behavior step-up authentication is meant to deliver.
The lifecycle of an elevated authentication context
Baseline established
A user logs in normally, receiving a token reflecting the baseline authentication context.
Elevation triggered
The user attempts a sensitive action, and a step-up request is issued and satisfied.
Elevated context persists (per configured policy)
Depending on the deployment’s chosen approach, the elevated context either persists for the rest of the session or is scoped narrowly to a short window or single action.
Context expires or session ends
Eventually, either the elevated context’s own validity window closes, or the underlying session itself ends, requiring a fresh step-up for any future sensitive action.
Because step-up authentication builds on top of the same underlying session, all the session revocation and timeout mechanisms discussed elsewhere still apply fully — a revoked session immediately invalidates any elevated context along with it, since the elevation was never a separate credential of its own, just a richer description of the same session’s authentication history.
6Advantages, Disadvantages & Trade-offs
Advantages
- Matches authentication friction to actual risk, rather than applying the same bar uniformly across every action
- Reduces unnecessary friction for the vast majority of low-risk, everyday interactions
- Provides meaningfully stronger protection specifically for the smaller set of genuinely sensitive actions that need it
- Built on standardized OpenID Connect claims, making the strength of any given login portable and interpretable across applications
Disadvantages & Trade-offs
- Requires deliberate, ongoing application-level work to correctly identify which actions actually warrant a step-up
- Adds real complexity to authentication flow design and token verification logic compared to a single, uniform login
- Poorly scoped elevation persistence (too long a window) can quietly undermine the security benefit it’s meant to provide
- Introduces a genuinely new class of bug — an application that requests a step-up but fails to actually verify the returned context, silently proceeding as if it had
A building with a single uniform security checkpoint at the front door is simple to design but forces an uncomfortable trade-off between convenience and protecting its most sensitive areas. A building with layered checkpoints — light at the front, progressively stronger deeper in — better matches security to actual risk, but it takes real architectural thought to decide exactly where each checkpoint belongs, and ongoing diligence to make sure nobody quietly bypasses one.
7Security
The critical importance of server-side verification
The single most important security practice around step-up authentication is ensuring the application genuinely checks the acr claim in the token it receives back, on its own server-side logic, before permitting the sensitive action — never relying on client-side assumptions, never assuming a redirect to Keycloak automatically implies success. A request for a stronger context is just that: a request. Only an actually-verified claim in a genuinely validated token constitutes proof that it was satisfied.
Context
It’s tempting, especially under time pressure, to treat a successful redirect back from Keycloak’s step-up flow as implicit proof the stronger authentication was completed, skipping an explicit server-side check of the returned token’s acr claim.
Decision
Always explicitly verify the acr claim on the server side, against the specific value the action actually requires, before permitting any sensitive action gated by step-up authentication — never infer success from the flow’s completion alone.
Consequence
A misconfigured flow, an unexpected fallback path, or a manipulated client-side redirect cannot silently bypass the intended protection, since the actual gate is the server-side claim check, not the client-visible flow.
Scoping elevation duration deliberately
How long an elevated authentication context remains valid is itself a meaningful security decision. Too short a window creates excessive friction, repeatedly prompting users for actions in quick succession. Too long a window risks the elevated context becoming stale — still technically present in a session, but no longer reflecting genuinely fresh, recent proof of identity, especially relevant if a session could have been silently taken over sometime after the original step-up occurred.
Implementing step-up authentication but caching the “user has stepped up” state entirely on the client side (in browser storage or a cookie), rather than relying on the actual signed token claim — a client-side flag can be manipulated far more easily than a cryptographically signed assertion from Keycloak.
Step-up authentication and the broader threat model
It’s worth being precise about what step-up authentication protects against, and what it doesn’t. It raises the bar specifically for the moment a sensitive action is attempted, meaning an attacker who has only compromised a weaker, baseline credential still faces an additional, targeted barrier before reaching the most damaging actions. It does not, by itself, protect the baseline login from compromise in the first place, nor does it substitute for other session security fundamentals like proper revocation and secure token handling — it’s a complementary, additional layer focused specifically on the highest-risk moments.
8Monitoring, Logging & Metrics
Step-up trigger rate by action type
Tracking how often each specific sensitive action actually triggers a step-up request, helping validate that the application’s own sensitivity classification matches real usage patterns.
Step-up completion versus abandonment rate
Monitoring how often users successfully complete a requested step-up versus abandoning the action entirely, which can reveal whether the added friction is disproportionate to the actual risk for a given action.
Silent satisfaction rate
Tracking how often a step-up request is satisfied silently because the existing session already met the requirement, versus requiring an actual new challenge — useful for understanding how much friction users genuinely experience in practice.
Claim verification failure rate
Logging cases where an application’s server-side check finds the returned acr claim doesn’t actually meet the required level, which should be rare and worth investigating whenever it occurs.
A practical monitoring habit
Teams operating step-up-protected sensitive actions often build a specific dashboard panel comparing completion and abandonment rates across different action types, using a disproportionately high abandonment rate on any specific action as a signal worth investigating — either the step-up requirement is miscalibrated for that action’s actual risk level, or the challenge itself presents an unexpected usability problem worth addressing.
9Design Patterns & Anti-patterns
Proven patterns
Risk-tiered action classification
Define a small, clear set of risk tiers (standard, elevated, critical) with corresponding required authentication contexts, and consistently classify every sensitive action against this shared scale rather than deciding ad hoc, action by action.
Centralized claim verification
Build the server-side acr claim verification logic into a shared library or middleware used consistently across every protected action, rather than letting each team implement its own, potentially inconsistent check.
Context expiry proportional to sensitivity
Scope how long an elevated context remains valid based on the sensitivity of the actions it protects — shorter windows for the most critical actions, more lenient windows for moderately elevated ones.
Graceful, explanatory step-up prompts
Design the user-facing step-up challenge to clearly explain why the extra step is needed for this specific action, improving completion rates by making the friction feel justified rather than arbitrary.
Anti-patterns to avoid
Anti-pattern
- Requesting a stronger authentication context but never actually verifying the returned claim on the server side
- Applying step-up requirements inconsistently across similarly sensitive actions, based on which team happened to implement each one
- Setting an indefinitely long elevation window, effectively turning a one-time step-up into a permanent, un-re-verified privilege
- Presenting step-up challenges with no context or explanation, leading to confusion and unnecessary abandonment
Instead, do this
- Always explicitly verify the returned authentication context claim before permitting the protected action
- Apply a consistent, shared risk-classification scheme across every sensitive action in the application
- Scope elevation duration deliberately, proportional to actual sensitivity
- Give users clear, brief context for why a step-up is being requested at that specific moment
10Best Practices & Common Mistakes
Best practices
Maintain a documented action-to-context mapping
Keep a clear, accessible record of which specific actions require which authentication context level, so decisions are consistent and reviewable over time.
Test the step-up boundary explicitly
Include automated tests specifically verifying that an insufficiently authenticated session is correctly blocked from a protected action, not just that a properly elevated one succeeds.
Review sensitivity classifications periodically
Revisit which actions are classified as sensitive as the application evolves, since new features can introduce genuinely high-risk actions that weren’t accounted for at initial design time.
Coordinate authentication flow changes across teams
Since the underlying conditional authentication flow is realm-wide configuration, changes to it should be communicated clearly to every team relying on specific context levels it provides.
Common mistakes
Treating step-up authentication as purely a Keycloak configuration task, without recognizing that correctly identifying sensitive actions and verifying returned claims is fundamentally application-level responsibility that Keycloak cannot fulfill on its own.
Inconsistently applying step-up requirements across functionally similar actions implemented by different teams, creating confusing gaps where one sensitive action is protected and a comparably sensitive one is not.
Assuming a successfully completed step-up flow, once verified for one action, remains valid indefinitely for every future action without any deliberate re-verification policy, gradually eroding the protection’s intended freshness.
11Real-world & Industry Examples
Banking and financial services
Financial platforms routinely require step-up authentication before approving transfers above a certain amount, changing account recovery details, or adding a new payee, layering extra verification precisely at the moments of greatest financial risk.
Healthcare records systems
Patient portals often require step-up authentication before granting access to especially sensitive categories of medical records, balancing everyday convenience against the heightened privacy stakes of specific data categories.
Enterprise administrative consoles
Internal admin tools frequently require step-up authentication before destructive or high-impact actions — deleting a production resource, modifying a critical security setting — even for administrators already logged in with a standard baseline credential.
E-commerce and marketplace platforms
Online marketplaces sometimes require step-up authentication before a seller changes payout banking details or before an unusually large purchase, targeting extra scrutiny at the specific transactions most attractive to fraud.
A representative scenario
A digital banking platform initially required the same password-based login for every action, from checking a balance to approving a large wire transfer. After a security review highlighted this as a disproportionate risk for high-value transactions, the team implemented step-up authentication specifically for transfers above a defined threshold and for adding new payees — requiring users to complete a WebAuthn challenge at exactly those moments, while leaving routine balance checks and smaller transactions unaffected. The result meaningfully raised the bar for an attacker who had only compromised a stolen password, without adding friction to the vast majority of everyday, lower-risk interactions.
12FAQ
13Summary and Key Takeaways
Key Takeaways
- Step-Up Authentication requests a stronger proof of identity for specific, sensitive actions, without disrupting a user’s broader, already-established session.
- It’s built on standardized OpenID Connect claims — acr (authentication context strength) and amr (methods used) — giving it a portable, well-understood foundation rather than a proprietary mechanism.
- Keycloak implements it through conditional authentication flows that respond to a requested context level, satisfying it silently if the session already qualifies, or prompting a stronger challenge if it doesn’t.
- Deciding which actions actually warrant a step-up is fundamentally an application-level responsibility that Keycloak’s mechanism alone cannot fulfill.
- The single most important security practice is explicitly verifying the returned acr claim server-side, never assuming a completed redirect implies success.
- How long an elevated context persists is a deliberate security trade-off, scoped proportionally to the sensitivity of the actions it protects.
- Well-designed step-up authentication meaningfully improves the balance between security and usability, concentrating friction specifically where risk genuinely warrants it.
- Real-world adoption spans banking, healthcare, enterprise administration, and e-commerce — anywhere a small subset of actions carries disproportionately higher risk than everyday use.