OIDC step-up: bring SAML's Comparison (exact/minimum/maximum) semantics to acr_values #51533

JoWe112 · 2026-08-07T09:26:44Z

JoWe112
Aug 7, 2026

While building an OIDC step-up setup — where the first-factor method is chosen from the requested ACR
(password / passkey / X.509 client cert) — I hit two OIDC limitations that SAML step-up doesn't have.
Floating it here in Ideas before proposing a formal enhancement.

The gap

SAML step-up already honours RequestedAuthnContext Comparison with exact / minimum / maximum
semantics (SamlProtocolUtils.checkLoAExact/checkLoAMinimum/checkLoAMaximum, behind
STEP_UP_AUTHENTICATION_SAML). The OIDC side has no equivalent:

Condition - Level of Authentication is cumulative only (requestedLoa >= configuredLoa). There's
no "exact" mode, so you can't express "acr=X ⇒ exactly method A" — a higher level always also runs
the lower method.
Multi-valued acr_values is always collapsed to its minimum. acr_values is a space-separated
preference list (RFC 9470 §3), but AuthorizationEndpoint reduces it with .min(), so
acr_values="silver gold" silently becomes silver. There's no way to pick the highest acceptable
level or honour preference order.

Net effect: the same client intent behaves differently depending on whether the client speaks OIDC or
SAML.

The idea

Two small, backwards-compatible additions behind the existing STEP_UP_AUTHENTICATION feature:

a comparison mode on the LoA condition — minimum (today's default) vs exact;
a configurable reduction for multi-valued acr_values — minimum (default) vs maximum (and maybe
later exact-any / preference-order).

Together, exact + maximum means "authenticate at exactly the highest requested level", which is what
makes disjoint ACR→method selection possible over OIDC.

Concrete example

Realm map low→1, high→2:

Today: acr_values="low high" → collapses to 1 → password.
With maximum: acr_values="low high" → 2 → passkey.
With exact on the level-2 subflow: it runs only for level-2 requests, not as a step on top of
level 1.

Open questions

Mirror the SAML Comparison model directly (share the enum/semantics), or an OIDC-specific config?
Where should the reduction policy live — client, realm, or both? And the comparison mode:
per-execution on the condition (like loa-condition-level)?
Is maximum enough to start, or should exact-any / preference-order come in from the beginning?
Any concerns about the interplay with Minimum ACR Value (the floor) and the acr claim mapping?

I have a working reference implementation (as external ConditionalAuthenticator SPIs) plus a PR-scoped
design, and I'm happy to do the PR if there's appetite. Curious what the maintainers and community think.

mabartos · 2026-08-07T12:11:41Z

mabartos
Aug 7, 2026
Collaborator

cc: @rmartinc

0 replies

JoWe112 · 2026-08-07T13:36:47Z

JoWe112
Aug 7, 2026
Author

Update / correction to myself.

Since opening this, I found that the practical goal behind the proposal — selecting the login method
disjointly by ACR (password / passkey / X.509) and making the highest of several requested acr_values
win — is already achievable natively in Keycloak 26.2+, without the comparison/reduction changes I
asked for here.

The mechanism is "Dynamic Authentication Flow selection using Client Policies", combining two
built-ins:

acr-condition (client-policy condition) — matches the requested ACR
(AcrUtils.getAcrValues(...).contains(<acr>), i.e. exact membership), and
auth-flow-enforcer (client-policy executor) — routes the request to a whole authentication
flow and sets the achieved LoA (auth-flow-loa).

So you make one flow per method (flow-password, flow-passkey, flow-x509) and one policy per ACR
(low → flow-password, high → flow-passkey, x509 → flow-x509). For a multi-valued acr_values,
every matching policy runs and the last one wins, so ordering the policies low → high makes the
highest requested method win — which sidesteps the .min() collapse I complained about, because it
selects a whole flow rather than reducing to a level. No acr_values → the client's Default ACR Values
decides. The token acr comes from auth-flow-loa via the ACR-to-LoA map.
Docs: Using Client Policies to Select an Authentication Flow.

I verified this end-to-end (password / passkey / X.509, single- and multi-valued acr_values) — a full
runnable how-to + PoC is here: https://github.com/JoWe112/keycloak-acr-routing-poc.

For my use case this fully covers it — flow selection gives "exact" behaviour for free (the target flow
contains only the one method, so there's no cumulative lower step and nothing to reduce), so the .min()
collapse and the missing exact mode both stop mattering once you route by flow. I've removed the custom
SPIs and I'm no longer blocked, so from my side this can be closed.

The only thing native flow selection doesn't touch is the Condition - Level of Authentication
authenticator itself — it's still cumulative with no exact mode — so if there's still appetite for
SAML-style comparison parity on the condition, I'm happy to help with a PR; otherwise this is
effectively solved.

One separate gap I did hit while building the PoC (flagging it here for completeness, though it's really
its own topic): there is no core authenticator to enrol a passkey in-flow for a user who doesn't
have one yet. The webauthn-register-passwordless required action exists, but the native ways to trigger
it are either a default required action (persists and re-prompts on every login, for every user) or an
application-initiated action (kc_action=webauthn-register-passwordless&skip_if_exists=true, which the
client has to drive) — neither is a flow-driven, conditional, session-scoped "this user just fell back to
password, offer them a passkey now" step. So the one piece of custom code I still needed is a tiny
authenticator that adds that required action to the authentication session (not the user account), so
it applies to this login only. That's the same in-flow capability requested in
#25779.

0 replies

Navigation Menu

Repository navigation

OIDC step-up: bring SAML's Comparison (exact/minimum/maximum) semantics to acr_values #51533

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

OIDC step-up: bring SAML's Comparison (exact/minimum/maximum) semantics to acr_values #51533

Uh oh!

JoWe112 Aug 7, 2026

The gap

The idea

Concrete example

Open questions

Replies: 2 comments

Uh oh!

mabartos Aug 7, 2026 Collaborator

Uh oh!

JoWe112 Aug 7, 2026 Author

JoWe112
Aug 7, 2026

mabartos
Aug 7, 2026
Collaborator

JoWe112
Aug 7, 2026
Author