Repository navigation
Conversation
… 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>
Contributor
There was a problem hiding this comment.
🟡 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>
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Closes #54497
Replaces #54520 and #54499. Both earlier attempts changed more than the bug: #54499 kept resolving
amrat 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.isAmrValidappliesdefault.reference.maxAge(default0) 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 inamrwhen 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
0is "valid just for the current authentication, but not any subsequent SSO authentications", and implements it by fixing the level on the client session inTokenManager.attachAuthenticationSession. Theamrimplementation borrowed the field and applied it to the current authentication too.What changes
amrkeeps "valid just for the current authentication" the same way the level does.AuthenticatorUtils.updateCompletedExecutionsalso records the executions completed during the current authentication, as an auth note soresetFlowdiscards 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 asamr-current-authentication-executions, next to theLEVEL_OF_AUTHENTICATIONthatTokenManager.attachAuthenticationSessionset 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.AmrProtocolMapperreports 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.isAmrValidtreats a max age of0as 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 age0, token requested 20 seconds after the password form, expects["password"]. Fails onmainwithexpected: <1> but was: <0>.testAmrPasswordTotpDelayedCodeExchange(new): password and OTP both with max age0, 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 age10reports[]. 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).
testAmrPastMaxAgeWithinCurrentAuthenticationis unchanged from #54520, where it was run againstmainand failed withexpected: <1> but was: <0>; the code it exercises onmainhas not changed since.