Built-in WebAuthn step-up primitive (default StepUpService) for credential-altering operations

[devondragon]

Summary

Ship a built-in WebAuthn step-up primitive so consumers get step-up re-authentication out of the box, rather than having to implement the StepUpService SPI themselves.

Background

The security concern from SUF-02 (#328) is already closed: POST /user/setPassword now requires a StepUpService when one is provided and is disabled by default otherwise (shipped in #334). This ticket is the enhancement — a default, framework-provided step-up implementation — not a security gap.

Design

Revised 2026-08-18 after a spike (findings, assumptions pinned in #364). The original design proposed custom challenge/verify endpoints with a server-side challenge store, written before this project moved to Spring Boot 4.1 / Spring Security 7.1. SS 7.1 supplies the mechanism directly, so that surface is dropped. The superseded design is preserved in the local design doc's appendix.

Step-up is expressed as a freshness requirement on the WebAuthn factor:

• WebAuthnAuthenticationProvider stamps FactorGrantedAuthority.fromAuthority("FACTOR_WEBAUTHN") on every assertion, with issuedAt defaulting to now.
• RequiredFactor.validDuration(ttl) plus AllRequiredFactorsAuthorizationManager deny a factor older than the TTL.
• AbstractAuthenticationProcessingFilter with mfaEnabled=true merges a re-assertion into the existing session, deduping by authority string in favor of the new authorities. Re-running /login/webauthn while logged in therefore refreshes the clock and keeps the user's roles.

So the ceremony is the ordinary passkey login, re-run. No new endpoints, no challenge storage, no session marker, no library-owned WebAuthnRelyingPartyOperations bean, and no second client ceremony.

The StepUpService SPI shipped in #334 is unchanged: a default implementation satisfies boolean isStepUpSatisfied(User, String, HttpServletRequest) by inspecting the current Authentication, so 5.3.x consumer implementations keep working and still take precedence.

Work

• user.security.stepUp.* config: enabled (default false), ttlSeconds (default 300), factor (default WEBAUTHN).
• Default StepUpService bean under @ConditionalOnMissingBean(StepUpService.class), applying the validDuration factor check.
• Activate filter factor-merging when step-up is enabled, not only when user.mfa.enabled=true. The MfaFilterMergingConfiguration warning about flipping mfaEnabled on consumer-defined filters carries over and must be repeated in the step-up docs.
• Extend the gate to WebAuthnManagementAPI delete/rename, which today are no-ops for passwordless accounts because requireCurrentPasswordIfSet has no password to check.
• Sensitive operations rejected for staleness return 401 with code step-up-required; the client re-runs the passkey ceremony and retries.
• Reject FACTOR_-prefixed authority names in user.roles-and-privileges at startup. AllRequiredFactors resolves a required factor by taking the first authority matching by string and type-checking only that one, and the provider appends its stamp after the UserDetailsService's authorities, so a consumer privilege named FACTOR_WEBAUTHN sorts first and shadows the genuine factor. The gate then denies immediately after a real assertion: fail-closed, but step-up becomes permanently unsatisfiable with an opaque symptom. Pinned in test: pin Spring Security factor-freshness behavior for WebAuthn step-up #364.
• Docs (CONFIG.md, dsspringuserconfig.properties) and tests.

Open decisions

• Binding model. Factor freshness is a per-session time window: one ceremony authorizes any sensitive op inside the TTL. The superseded design was single-use and action-bound. Weaker binding, standard mechanism, mitigated by a short TTL.
• Accounts with no passkey. OAuth-only accounts have no WEBAUTHN factor to refresh. Either leave them on the existing allowInitialPasswordSetWithoutStepUp behavior, or make the required factor configurable, since PASSWORD and the other factors carry the same issuedAt.

Not yet verified

Step-up is a full re-login, so the session-fixation strategy runs, the documented duplicate InteractiveAuthenticationSuccessEvent fires, and the login JSON response lands mid-flow. Nothing in the code looks problematic, but only a browser can confirm it. That is the demo-app work below.

Scope / effort

Roughly a day for the library side, down from the original feature-scale estimate. Not fully validated end to end until the demo-app ceremony lands.

References

• Spike findings and evidence: comment above; pinned framework assumptions in test: pin Spring Security factor-freshness behavior for WebAuthn step-up #364.
• Interim SPI + default-disable: security: remaining SUF fixes (SUF-02 step-up, SUF-05 reset token, SUF-06 hardening) #334 (merged), StepUpService, user.security.allowInitialPasswordSetWithoutStepUp.
• Original finding: Security: initial password creation on passwordless accounts lacks step-up and session handling (SUF-02) #328.
• Demo-app client work: Handle step-up-required (401) by re-running the passkey ceremony on sensitive operations SpringUserFrameworkDemoApp#75.

[devondragon]

Spike result: build this on Spring Security's factor freshness, not on custom step-up endpoints

The design in this ticket (and the local design doc it points at) predates the move to Spring Boot 4.1 / Spring Security 7.1. SS 7.1 already provides everything step-up needs, so most of the proposed surface can be dropped.

What the framework already gives us

• FactorGrantedAuthority carries issuedAt, defaulting to Instant.now(), and WebAuthnAuthenticationProvider stamps FactorGrantedAuthority.fromAuthority("FACTOR_WEBAUTHN") on every successful assertion. An ordinary passkey login sets the clock.
• RequiredFactor.Builder.validDuration(Duration) plus AllRequiredFactorsAuthorizationManager deny an expired factor (RequiredFactorError.createExpired).
• AbstractAuthenticationProcessingFilter#doFilter, with mfaEnabled=true, merges a new authentication into the existing one for the same principal, deduping by authority string in favor of the new authorities. So re-running /login/webauthn while already logged in refreshes issuedAt and preserves the session's roles.

This project already wires both halves for MFA (MfaConfiguration, MfaFilterMergingConfiguration), and MfaLoginIntegrationTest already proves the merging post-processor reaches the DSL-built filters.

Verified, not assumed

WebAuthnStepUpFactorAssumptionsTest in #364 pins four behaviors, all passing:

1. validDuration(5m) denies a 30-minute-old WEBAUTHN factor and grants a just-issued one.
2. Re-asserting while authenticated yields exactly one WEBAUTHN factor bearing the new issuedAt, retains ROLE_USER, and flips the gate from denied to granted.
3. Control: with merging off, the session's authorities are replaced, so merging must be enabled deliberately.
4. The refreshed factor survives WebAuthnAuthenticationSuccessHandler's DSUserDetails conversion.

The tests stub only assertion verification (that needs an authenticator); everything else is the real framework code path.

What drops out of scope

No POST /user/stepup/options, no POST /user/stepup/verify, no server-side challenge store or session marker map, no library-owned WebAuthnRelyingPartyOperations bean, and no second client ceremony. The client re-runs the existing passkey login ceremony and retries the original call.

It also removes the SPI problem: the design doc assumed a richer StepUpService, but what shipped in #334 is boolean isStepUpSatisfied(User, String, HttpServletRequest). A default implementation that inspects the current Authentication fits that signature unchanged, so no breaking change and no deprecation cycle for consumers who implemented the SPI in 5.3.x.

Remaining work

• user.security.stepUp.* config (enabled, ttlSeconds, factor), default enabled=false.
• Default StepUpService bean under @ConditionalOnMissingBean, applying a validDuration factor check.
• Activate filter merging when step-up is enabled, not only when user.mfa.enabled=true. The MfaFilterMergingConfiguration warning about flipping mfaEnabled on consumer-defined filters carries over.
• Extend the gate to WebAuthnManagementAPI delete/rename, which are still no-ops for passwordless accounts.
• Docs, tests, and a rewrite of demo-app issue Handle step-up-required (401) by re-running the passkey ceremony on sensitive operations SpringUserFrameworkDemoApp#75, which is written against the old endpoint contract and is now much smaller.

Closer to a day than the feature-scale estimate on this ticket.

Two decisions still open

• Binding model. Factor freshness is a per-session time window: one ceremony authorizes any sensitive op inside the TTL. The original design was single-use and action-bound. Weaker binding, standard mechanism, mitigated by a short TTL.
• Accounts with no passkey. OAuth-only accounts have no WEBAUTHN factor to refresh. Either leave them on the existing allowInitialPasswordSetWithoutStepUp behavior, or make the required factor configurable, since PASSWORD and the others carry the same issuedAt.

Not yet verified

Step-up is a full re-login, so the session-fixation strategy runs, the documented duplicate InteractiveAuthenticationSuccessEvent fires, and the login JSON response lands mid-flow. Nothing in the code looks problematic, but this can only be confirmed in a browser, via the demo app's virtual-authenticator Playwright setup.

The local design doc has been revised to this approach, with the superseded custom-endpoint design kept as an appendix.

[devondragon]

Decisions on the two open questions

Binding model: session freshness window, TTL default 120s. No single-use, no per-action binding.

The threat is an attacker holding a session cookie and no authenticator, acting whenever they choose. Any freshness requirement closes that outright, since they can never produce a recent factor. Single-use and action-binding only help against an attacker sharing the session concurrently and piggybacking on the legitimate user's ceremony inside the window, who could equally interfere at the UI level. Not worth reintroducing bespoke state, which is what the redesign removed.

The design doc's 300s becomes 120s: the ceremony immediately precedes the operation, so 2 minutes is generous and it halves the piggyback window for free. Configurable.

Documented residual: within the TTL, one ceremony authorizes any credential-altering operation on that session.

Note for any future single-use work: do not consume the factor by removing it. If user.mfa.factors includes WEBAUTHN, removing that authority revokes access to every .authenticated() endpoint, because MFA enforcement reads the same authority. Consume by re-stamping with a backdated issuedAt, since MFA checks presence and step-up checks age.

Accounts with no passkey: configurable factor list, default WEBAUTHN only, OAuth-only accounts keep today's behavior.

setPassword is reachable only for accounts with no password, so this affects passkey-only and OAuth-only accounts. Passkey-only is fully covered. For OAuth-only, the gate denies and user.security.allowInitialPasswordSetWithoutStepUp keeps governing the flow exactly as it does today, so nothing regresses.

OAuth2LoginAuthenticationProvider does stamp FACTOR_AUTHORIZATION_CODE, so the mechanism extends in principle, but it is not being used here: refreshing it round-trips through the IdP and, with a live IdP session, usually completes with no user interaction, proving the IdP session is alive and nothing about presence. Making it real needs prompt=login or max_age=0 on a step-up-specific authorization request, which is per-provider work.

Proper coverage for OAuth-only accounts is an emailed confirmation link reusing the password-reset mechanism. Separate ticket if it is wanted.

Resulting config:

user.security.stepUp:
  enabled: false
  ttlSeconds: 120
  factors: [WEBAUTHN]   # any-of; PASSWORD, OTT, AUTHORIZATION_CODE also available

[devondragon]

Acceptance criteria

Derived from the decisions already recorded above plus findings from reviewing #365. Status is against feat/webauthn-step-up at 01a8435 (rebased on 5.3.2).

The decisions in the previous comment were sound; what was missing was the translation from "here's what we decided" to "here's how we'll know". At least one defect came from exactly that gap: the OAuth-only decision was written correctly in prose and the code shipped doing the opposite.

A. Default-off contract

• A1 With no user.security.stepUp.* configuration, no StepUpService bean exists and setPassword, passkey delete, and passkey rename behave exactly as in 5.3.2.
• A2 A consumer-supplied StepUpService takes precedence over the built-in one, including when stepUp.enabled=true.
• A3 A consumer that adopted the SPI in 5.3.1 and has not set stepUp.enabled=true sees no change to passkey delete/rename. Currently fails: WebAuthnManagementAPI.requireCredentialProof keys off bean presence, not the property, so their existing bean starts gating two operations it was never written for and receives two new action values.

B. Configuration

• B1 ttlSeconds defaults to 120 and is configurable.
• B2 factors defaults to [WEBAUTHN], is evaluated any-of, and unknown or empty values fail startup.
• B3 A non-positive ttlSeconds fails startup. Currently fails: @Min(1) is inert because StepUpConfigProperties lacks @Validated. ttlSeconds=0 binds and denies every gated operation forever.
• B4 WEBAUTHN in factors with user.webauthn.enabled=false fails startup, matching the equivalent check on user.mfa.factors.
• B5 Factor names normalize independently of the JVM default locale.

C. Freshness semantics

• C1 A configured factor issued within the TTL satisfies step-up; one issued outside it does not; an absent factor does not.
• C2 A fresh factor on one principal does not authorize an operation targeting another.
• C3 Within the TTL a single ceremony authorizes any number of credential-altering operations on that session. Accepted and documented, not a defect.

D. Accounts that cannot satisfy step-up

• D1 An OAuth-only account with stepUp.enabled=true and allowInitialPasswordSetWithoutStepUp=true can still set an initial password. This is the criterion the decisions comment stated in prose and the original implementation violated.
• D2 The same account with the flag left false gets 403 code 7 (disabled), not 401 code 6 (denied).
• D3 With factors=[PASSWORD], a passwordless passkey-holder is not permanently locked out of passkey rename and delete.
• D4 A consumer SPI implementation written before canSatisfyStepUp existed keeps being enforced (default true).

E. Threat model

• E1 An authenticated session holding no registered passkey cannot reach a state where WEBAUTHN step-up is satisfied. Currently fails. POST /webauthn/register requires only a session, so an attacker with a stolen cookie on a passwordless account can enroll their own passkey, assert with it to earn a fresh factor, and satisfy every gate. The claim in the design above that such an attacker "can never produce a recent factor" is false as implemented, and that claim was copied into DSFactorFreshnessStepUpService and CONFIG.md. Either gate enrollment or narrow the claim in all three places.
• E2 Passkey deletion cannot bypass the gate through an alternate endpoint. Closed in fix: deny Spring Security's built-in WebAuthn credential-delete endpoint (GHSA-3cv9-vgqh-jwpm) #366 / GHSA-3cv9-vgqh-jwpm, released in 5.3.2.
• E3 A granted authority named FACTOR_* cannot satisfy MFA enforcement or shadow a genuine factor. Partially met. FactorAuthorityNameValidator reads user.roles.roles-and-privileges only; authorities are granted from the role/privilege tables and RolePrivilegeSetupService never deletes, so a row surviving its removal from config still grants the counterfeit while the check passes clean. The @PostConstruct also never runs under spring.main.lazy-initialization=true. Either extend it to the database and move to ContextRefreshedEvent, or narrow the JavaDoc, which currently reads as if the whole authority space is covered.

F. Client contract

• F1 A step-up rejection on the passkey endpoints returns 401 with error code step-up-required. Implemented but untested — WebAuthnManagementAPIAdviceTest has no case for it, and WebAuthnStepUpRequiredException extends WebAuthnException, so losing the handler would silently fall through to 400 with a null error field.
• F2 A step-up rejection on setPassword returns 401 code 6; the disabled-by-default path returns 403 code 7.

G. Documentation

• G1 CONFIG.md property names, defaults, and types match StepUpConfigProperties and dsspringuserconfig.properties.
• G2 No JavaDoc or document states the library lacks step-up. Currently fails: WebAuthnManagementAPI.java:66-70 and MIGRATION.md:215 both still say "this library does not yet implement a WebAuthn step-up assertion".
• G3 The documented threat model matches what is enforced. Blocked on E1.

H. Verification

• H1 ./gradlew check green, ./gradlew javadoc clean.
• H2 Browser-verified end to end: session fixation strategy, the duplicate InteractiveAuthenticationSuccessEvent, and the login JSON response landing mid-flow. Tracked in Handle step-up-required (401) by re-running the passkey ceremony on sensitive operations SpringUserFrameworkDemoApp#75 and still the gate on calling this feature done.

Summary

18 of 26 met. The open ones are A3, B3, E1, E3, F1, G2, G3, H2.

E1 is the only one needing a product decision rather than work: gate enrollment, or narrow the claim. Everything else is bounded.