Per-client `default.acr.values=strong` + cross-client SSO that preserves LoA — are we approaching step-up idiomatically? #49276

ymajoros · 2026-05-23T19:56:59Z

ymajoros
May 23, 2026

Context / requirements

A single realm with a mix of OIDC clients, some requiring strong authentication (LoA ≥ 2) and some accepting weak (LoA 1).

Strong-required clients carry default.acr.values=strong + minimum.acr.value=strong on the client; realm has acr.loa.map = {"strong": 2}.
Weak-only client carries neither.
Users may authenticate via:
- password + TOTP (built-in auth-otp-form inside an existing Conditional 2FA subflow)
- Keycloak-native passkey (the conditional-UI button on UsernamePasswordForm dispatching to webauthn-authenticator-passwordless)
- external IdP via Identity Provider Redirector
Cross-client cookie SSO between strong clients must be silent: once the user has reached LoA 2 on any strong client, navigating to another strong client must not re-prompt.

We're on Keycloak 26.5.

What we ended up building

We've iterated through about five flow shapes (one of which broke the realm 3×) and landed on this — but it feels like a lot of bespoke pieces for what we expected to be a stock primitive.

Flow shape (a copy of the built-in `browser` flow with additions, provisioned on every backend startup)

browser-custom
├── Cookie [ALT]                                              ← built-in
├── Identity Provider Redirector [ALT]                        ← built-in
├── Kerberos [DISABLED]
├── browser-custom Organization [ALT]
└── browser-custom forms [ALT]
    ├── Username Password Form [REQUIRED]                     ← built-in; also dispatches passkey via conditional UI
    ├── promote-on-passwordless [CONDITIONAL]                 ← OURS
    │   ├── Condition - credential [REQUIRED]                 ← built-in conditional-credential
    │   │                                                       (credentials=webauthn-passwordless, included=true)
    │   └── Promote LoA to 2 [REQUIRED]                       ← OURS — calls AcrStore.setLevelAuthenticated(2)
    ├── promote-on-otp [CONDITIONAL]                          ← OURS
    │   ├── Condition - credential [REQUIRED]                 ← credentials=otp, included=true
    │   └── Promote LoA to 2 [REQUIRED]
    ├── strong-stepup [CONDITIONAL]                           ← OURS — tail step-up
    │   ├── Custom Conditional LoA [REQUIRED]                 ← OURS — custom ConditionalAuthenticator
    │   │                                                       (config loa-level=2)
    │   └── OTP Form [REQUIRED]                               ← built-in fallback factor
    └── browser-custom Browser - Conditional 2FA [CONDITIONAL] ← built-in OTP gate, unchanged

post-broker-loa-promote (top-level)                           ← OURS
└── Promote LoA to 2 [REQUIRED]                               ← assigned as postBrokerLoginFlowAlias on every IdP

The four bespoke pieces

Custom ConditionalAuthenticator (custom-conditional-loa). Same idea as the built-in conditional-level-of-authentication but with an explicit requestedLoa >= configuredLoa guard — see "Why a custom conditional" below.
A "set LoA" authenticator (loa-promotion) that calls AcrStore.setLevelAuthenticated(2) and immediately succeeds. Used as the body of every per-credential CONDITIONAL subflow above.
A LoA-MAP propagator — the same loa-promotion authenticator also implements AuthenticationFlowCallback, and its onTopFlowSuccess copies the auth-session LOA_MAP authNote to the user-session note (mirroring what the built-in ConditionalLoaAuthenticator.onTopFlowSuccess does), so that cookie SSO into a new client picks up the LoA via CookieAuthenticator.
An EventListener that, on a LOGIN event, writes the user-session LOA_MAP directly + writes a separate auth.methods user-session note (consumed by an oidc-usersessionmodel-note-mapper for the token's amr claim). On LOGIN events that have no credential_type / identity_provider markers in details, we have to distinguish "fresh password re-auth" from "cookie-restored SSO" so we don't wipe LOA_STRONG from the map on the latter — we use the presence of the auth-session LOA_MAP authNote (set by CookieAuthenticator.authenticate line ~56) as the discriminator.

Why a custom conditional

The built-in ConditionalLoaAuthenticator.matchCondition (see ConditionalLoaAuthenticator.java) has this early return:

int currentAuthenticationLoa = acrStore.getLevelOfAuthenticationFromCurrentAuthentication();
Integer configuredLoa = getConfiguredLoa(context);
if (configuredLoa == null) configuredLoa = Constants.MINIMUM_LOA;
int requestedLoa = acrStore.getRequestedLevelOfAuthentication(context.getTopLevelFlow());
if (currentAuthenticationLoa < Constants.MINIMUM_LOA) {
    // Fires unconditionally on every fresh login, BEFORE checking requestedLoa
    return true;
}
// ... only here does it check `requestedLoa < configuredLoa`

NO_LOA = -1 < MINIMUM_LOA = 0, so on every fresh login this returns true regardless of whether the request asked for any acr at all. A tail CONDITIONAL using the built-in therefore fires for every client — empirically reproduced: a tail-CONDITIONAL with deny-access body locked out our weak-only client because the condition matched for it too.

Our custom matchCondition:

if (requestedLoa < configuredLoa) return false;   // request didn't ask for this level
if (currentLoa >= configuredLoa) return false;    // already satisfied in this auth
if (acrStore.isLevelAuthenticatedInPreviousAuth(configuredLoa, maxAge)) {
    acrStore.setLevelAuthenticatedToCurrentRequest(configuredLoa);
    return false;                                  // satisfied in previous auth on this user session
}
return true;

That's the minimum we could find that yields the right behavior for both weak and strong clients on fresh login AND on cookie SSO.

Specific questions

Is there a simpler / canonical pattern we missed? Per-credential LoA promotion subflows + tail CONDITIONAL is a lot of plumbing for what feels like a standard requirement. Is there a built-in we should be using instead of a custom "set LoA" authenticator + conditional-credential? Something that says "this credential type implies LoA X" at the realm or authenticator level?
Is the bootstrap behavior of ConditionalLoaAuthenticator.matchCondition (returning true unconditionally when currentAuthenticationLoa < MINIMUM_LOA) intentional? If yes, what's the recommended placement that doesn't cause it to fire for clients that didn't request a higher LoA? If no, would a PR moving the requestedLoa < configuredLoa guard above the early return be welcome?
Per-credential LoA promotion as a first-class feature. Would the project accept a proposal for either (a) a realm-level credential-type → LoA map, or (b) an authenticator-config field "on success, set LoA to N"? Either would eliminate three of our four bespoke pieces.
minimum.acr.value enforcement timing vs in-flow LoA restoration on cookie SSO. When CookieAuthenticator restores LOA_MAP showing level 2 was previously achieved, and a fresh authorize request comes in for a client with minimum.acr.value=strong, the minimum.acr.value check appears to fire BEFORE in-flow conditionals get to restore LoA into the current request via setLevelAuthenticatedToCurrentRequest. We observe re-prompts after step-up that we wouldn't expect given the user session has the level. Is this a known interaction, expected behavior, or worth a separate issue with a repro?
Distinguishing cookie-restored LOGIN events from password re-auth. Both fire EventType.LOGIN with essentially identical details (no credential_type, no identity_provider). We worked around it by checking authSession.getAuthNote(Constants.LOA_MAP) — non-null implies cookie restoration. Would the team accept a feature request to add something like details.get("auth_source") ∈ {cookie, password, idp} to LOGIN events? Or is there an existing signal we missed?

Repro

Minimal repro of question 2 (the bootstrap behavior):

Realm r with acr.loa.map = {"strong": 2}.
Two clients: weak-only (no acr attributes), strong-required (default.acr.values=strong).
Copy browser to browser-r. At the tail of browser-r, add a CONDITIONAL subflow:
- conditional-level-of-authentication REQUIRED, config loa-condition-level=2, loa-max-age=0.
- deny-access REQUIRED.
Set browser-r as the realm's browser flow.
Authorize against weak-only in fresh incognito — expect login form; observe "Access denied" instead.

Versions: Keycloak 26.5.0, no preview features enabled beyond defaults.

What we'd love to confirm before filing issues

We've gone through this iteration cycle four times across a week and only landed on the current shape by reading Keycloak's source. If we missed something obvious, we'd love to know — that's why this is a Discussion and not an issue. If the answer is "yes you have to do all this", we'll happily file the bugs and RFEs with detailed repros or pull requests.

Thanks!

mg1986jp · 2026-05-28T02:31:09Z

mg1986jp
May 28, 2026

This is a tricky one. Setting default.acr.values=strong per client means that client will always require the "strong" LoA for authentication. But with SSO, if a user already has an active session from another client that authenticated at a lower LoA, the question is whether KC will step up or just pass through the existing session.

In Keycloak's current implementation, the default.acr.values on a client sets the requested ACR for new authentications. If there's an existing SSO session, KC checks whether the session's LoA meets the requested ACR. If it doesn't, it triggers step-up authentication.

So your approach should work idiomatically — set default.acr.values per client to define what level each client requires. KC will handle step-up automatically when a user moves from a "weak" client to a "strong" client within the same SSO session.

The main gotcha is that the session's LoA is stored at the session level, not per-client. So once a user steps up to "strong" for one client, all subsequent SSO logins in that session will be at "strong" level — there's no way to "step down" within the same session. That's usually fine but worth knowing.

0 replies

ymajoros · 2026-05-28T10:04:33Z

ymajoros
May 28, 2026
Author

Thanks — that matches the design intent. Session-level LOA_MAP is exactly what we're building on (AcrStore.setLevelAuthenticated writes it; CookieAuthenticator.authenticate restores it onto the new auth-session on cookie SSO; our piece 4 EventListener writes the same note for the same reason).

The friction we hit is empirical and the repro at the end of the post is the load-bearing part. With browser-r containing a tail CONDITIONAL of conditional-level-of-authentication REQUIRED + deny-access REQUIRED, authorize against a weak-only client that never sends acr_values — KC denies, and the trace says: "Condition '…' evaluated to true due the user not yet reached any authentication level in this session, configuredLoa: 40, requestedLoa: 10". The cause is the currentAuthenticationLoa < Constants.MINIMUM_LOA early-return in matchCondition, which short-circuits before the requestedLoa < configuredLoa guard. Same pattern as #28341, closed as a docs issue — but it's a real behavioural gap once a single realm hosts both weak and strong clients in the same browser flow, since the tail conditional then fires for both.

Two small proposals, smallest-first:

A PR moving the requestedLoa < configuredLoa guard above the < MINIMUM_LOA early-return in ConditionalLoaAuthenticator.matchCondition. That's the entire bootstrap fix.
An RFE for an authenticator-config set-loa-on-success knob (or a realm-level credential → LoA map). The AcrStore.setLevelAuthenticated-from-a-custom-authenticator pattern is already in the wild (discussion Level of authentication not set after IdP authentication #25272); the bespoke part is wrapping it with conditional-credential for per-credential promotion.

Happy to file both with full reproducers and a draft PR for (1). Is that the preferred path, or should #28341 be reopened with the evidence + PR attached?

0 replies

Navigation Menu

Repository navigation

Per-client `default.acr.values=strong` + cross-client SSO that preserves LoA — are we approaching step-up idiomatically? #49276

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Per-client default.acr.values=strong + cross-client SSO that preserves LoA — are we approaching step-up idiomatically? #49276

Uh oh!

ymajoros May 23, 2026

Context / requirements

What we ended up building

Flow shape (a copy of the built-in browser flow with additions, provisioned on every backend startup)

The four bespoke pieces

Why a custom conditional

Specific questions

Repro

What we'd love to confirm before filing issues

Replies: 2 comments

Uh oh!

mg1986jp May 28, 2026

Uh oh!

ymajoros May 28, 2026 Author

Per-client `default.acr.values=strong` + cross-client SSO that preserves LoA — are we approaching step-up idiomatically? #49276

ymajoros
May 23, 2026

Flow shape (a copy of the built-in `browser` flow with additions, provisioned on every backend startup)

mg1986jp
May 28, 2026

ymajoros
May 28, 2026
Author