Skip to content

Report amr references of the current authentication regardless of max age - #55273

Open
ajworkos wants to merge 3 commits into
keycloak:mainfrom
ajworkos:amr-current-authentication-pinned
Open

ajworkos wants to merge 3 commits into
keycloak:mainfrom
ajworkos:amr-current-authentication-pinned

Conversation

@ajworkos

@ajworkos ajworkos commented Nov 17, 2026 •

Copy link
Copy Markdown

Closes #54497

Replaces #54520 and #54499. Both earlier attempts changed more than the bug: #54499 kept resolving amr at mint time from the user session's shared map, and #54520 pinned the carried-over methods as well, which stops them expiring from refreshed tokens and changes what the max age means. This PR fixes the bug and nothing else.

The bug

AmrUtils.isAmrValid applies default.reference.maxAge (default 0) to every completed execution at the moment a token is minted, including the executions of the login being tokenized. With whole-second timestamps, a method the user just completed only appears in amr when the token is minted in the same second the authenticator finished. For a fixed configuration the claim is nondeterministic, and no configuration reaches the documented behavior: the server admin guide says the mapper reports "any authenticator execution the user successfully completes during the authentication flow", and the admin console help text describes the max age as how long a reference "is good for in an SSO session", which is the carry-over case.

The level of authentication has the same max age field with the documented meaning that 0 is "valid just for the current authentication, but not any subsequent SSO authentications", and implements it by fixing the level on the client session in TokenManager.attachAuthenticationSession. The amr implementation borrowed the field and applied it to the current authentication too.

What changes

amr keeps "valid just for the current authentication" the same way the level does.

  • AuthenticatorUtils.updateCompletedExecutions also records the executions completed during the current authentication, as an auth note so resetFlow discards it. Merging previously completed executions now keeps the current authentication's timestamp for an execution completed again, so a carried-over max age counts from the latest completion.
  • AuthenticationProcessor.attachSession, the one path every real authentication takes, fixes that list on the client session as amr-current-authentication-executions, next to the LEVEL_OF_AUTHENTICATION that TokenManager.attachAuthenticationSession set just before. Synthetic attachments, token exchange among them, leave it alone. A reused offline client session gets it copied from the online one, next to the pinned identities.
  • AmrProtocolMapper reports the fixed executions regardless of max age, resolved from the note itself, and every other execution in the user session's completed map only while within its max age, as today. Carried-over references still expire from refreshed tokens when their max age passes; that is the documented meaning of the knob and this PR does not change it.
  • AmrUtils.isAmrValid treats a max age of 0 as never carrying over, instead of carrying over within the same second. The help text and the server admin guide now state the default and what it means.

Client sessions attached before the upgrade have no note and keep today's behavior. Offline client sessions copy the note when they are created, as they copy the level.

Every path that touches a client session outside a real login (synthetic attachment by token exchange, offline reuse, the offline user session's snapshot of the completed map) treats this note the way it treats LEVEL_OF_AUTHENTICATION; where the two differ it is because the level has no equivalent of the offline sync.

Tests

AuthenticationMethodReferenceTest:

  • testAmrPastMaxAgeWithinCurrentAuthentication (new): max age 0, token requested 20 seconds after the password form, expects ["password"]. Fails on main with expected: <1> but was: <0>.
  • testAmrPasswordTotpDelayedCodeExchange (new): password and OTP both with max age 0, code exchanged five seconds after the OTP form, expects ["password", "totp"]. This is the scenario from the issue.
  • testAmrPastMaxAge (reworked): the first login reports ["password"]; a second login through the SSO cookie 20 seconds later with max age 10 reports []. The previous version of this test asserted [] for the first login's own tokens, which is the bug.

AI disclosure

Generated with an AI coding agent (Claude Code) from a prompt, then reviewed, built and tested locally by me. The test class passes locally against the built distribution (8 tests). testAmrPastMaxAgeWithinCurrentAuthentication is unchanged from #54520, where it was run against main and failed with expected: <1> but was: <0>; the code it exercises on main has not changed since.

… age

The Authentication Method Reference (AMR) protocol mapper applied each
execution's max age, default 0, at token-mint time to every completed
execution, including the ones of the login being tokenized. With
whole-second timestamps a method the user just completed only appeared
when the token was minted in the same second the authenticator finished,
and no configuration reached the documented behavior.

Fix the executions completed by the current authentication on the client
session in TokenManager.attachAuthenticationSession, next to the level of
authentication, and report them regardless of max age. Executions carried
over from earlier authentications in the SSO session stay subject to their
max age at mint time, and a max age of 0 never carries over.

Closes keycloak#54497

Signed-off-by: Adam Jenkins <adam.jenkins@workos.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved AMR session-state bugs can retain stale password authentication on offline refresh and discard valid authentication methods during offline-session reuse or token exchange.

3 open issues
What changed in this PR

Addresses #54497 by reporting authentication methods completed during the current login regardless of max age, while retaining expiration for methods carried over from earlier SSO authentications.

Changes:

  • Tracks current-authentication executions separately and stores them on the client session.
  • Exempts those executions from max-age checks and prevents zero-age references from carrying over.
  • Adds regression coverage and documents the max-age behavior and default.
File Description
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​oidc/​AuthenticationMethodReferenceTest.java Tests delayed token issuance and expiration on subsequent SSO login.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​utils/​AmrUtils.java Separates current-authentication references from age-limited references.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​TokenManager.java Stores or clears current-authentication execution IDs on the client session.
services/​src/​main/​java/​org/​keycloak/​protocol/​oidc/​mappers/​AmrProtocolMapper.java Reads current-authentication execution IDs when resolving AMR claims.
services/​src/​main/​java/​org/​keycloak/​authentication/​authenticators/​util/​AuthenticatorUtils.java Tracks current executions and preserves their latest completion timestamps.
server-spi-private/​src/​main/​java/​org/​keycloak/​models/​Constants.java Defines authentication and client session note keys.
js/​apps/​admin-ui/​maven-resources/​theme/​keycloak.v2/​admin/​messages/​messages_en.properties Clarifies max-age behavior in admin console help.
docs/​documentation/​server_admin/​topics/​authentication/​flows.adoc Documents AMR max age and its zero default.

Review effort: Balanced

…tications

Writing the note in TokenManager.attachAuthenticationSession let token
exchange, which attaches a synthetic authentication session to the target
client's existing session, clear the browser login's executions. Write it
in AuthenticationProcessor.attachSession instead, the one path every real
authentication takes, as an explicit empty list when the login completed
no execution.

Copy the note onto a reused offline client session, next to the pinned
identities, so a new offline token does not report the authentication
that created the offline client session. Resolve the note's executions
directly rather than as an exemption over the user session's completed
map, which on an offline session is a snapshot that never learns about
later logins.

Signed-off-by: Adam Jenkins <adam.jenkins@workos.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 15:10

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the AMR expiry-handling changes.

1 open issue
2 resolved since last review

Review effort: Balanced

…d later

The scenario that reported the bug: both executions configured with the
default max age of 0, and the authorization code exchanged a few seconds
after the OTP form. Both methods belong to the authentication being
tokenized, so both are reported whichever second the token is minted in.

Signed-off-by: Adam Jenkins <adam.jenkins@workos.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 15:23

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues require further changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

amr claim drops authenticator references from the current login unless the token is minted in the same second

2 participants