Skip to content

Cache username/email lookup queries for users already managed in the session - #54646

Open
dasniko wants to merge 1 commit into
keycloak:mainfrom
dasniko:user-cache-managed-user-query-caching
Open

dasniko wants to merge 1 commit into
keycloak:mainfrom
dasniko:user-cache-managed-user-query-caching

Conversation

@dasniko

@dasniko dasniko commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Closes #54645

UserCacheSession.getUserByUsername() and getUserByEmail() returned the already managed user before storing the lookup query, so a user loaded first by the other lookup never got the second query cached. On a warm email login with VERIFY_PROFILE enabled (default), DuplicateUsernameValidator then caused one getUserByUsername call to the user store on every login.

This restores the behaviour from before the 2016 user cache policy change: the query is cached on the managed path too, under the same conditions as the normal path (only for cached UserAdapters, same revision and lifespan), and only if the managed user still matches the lookup key. Invalidated users, NO_CACHE/uncached users and realm invalidations keep their current behaviour.

getUserByFederatedIdentity and getServiceAccount have the same early return. I left them out to keep this PR small.

Tests: new UserCacheQueryTest with a counting user storage provider. It fails without the fix and passes with it. The existing model, user storage, LDAP, organization-cache and admin-user tests in tests/base still pass, as do UserStorageTest, UserStorageFailureTest and LDAPExternalChangesTest against Quarkus.

Docs: no documentation change; this is an internal caching fix with no user-visible configuration or behaviour change.

Generative AI disclosure

Claude Code helped with the history analysis, the implementation, the tests and this description. I reviewed and understand the change and can explain and revise it.

…session

When a user was already loaded in the current session by another lookup,
for example by email on a login, getUserByUsername and getUserByEmail
returned the managed user before the lookup query was stored. The query
for the other key was therefore never cached and every following request
paid one lookup in the user store, e.g. the username lookup of the
user profile validation on each login with VERIFY_PROFILE enabled.

The early return dates back to the user cache policy change, which moved
the query caching below the adapter creation to skip uncached users.
Cache the query on the managed path as well, under the same conditions
as before: only for cached UserAdapters, with the same revision and
lifespan, and only if the managed user still matches the lookup key.

Closes keycloak#54645

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: Niko Köbler <niko@n-k.de>
@dasniko
dasniko requested review from a team as code owners November 4, 2026 16:12
Copilot AI balanced review requested due to automatic review settings November 4, 2026 16:12

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 change to avoid repeated username and email lookups during warm logins.

No open issues 🎉

What changed in this PR

Fixes #54645 by caching username and email lookup queries when the user is already managed in the session, avoiding repeated user-store lookups during warm logins.

Changes:

  • Adds shared query-caching logic with lookup-key matching and cache-policy safeguards.
  • Adds regression tests for both lookup orders, uncached users, invalidation, and local users.
  • Introduces and registers a counting user storage provider for the tests.
File Description
tests/​custom-providers/​src/​main/​resources/​META-INF/​services/​org.keycloak.storage.UserStorageProviderFactory Registers the counting provider factory.
tests/​custom-providers/​src/​main/​java/​org/​keycloak/​tests/​providers/​federation/​CountingUserStorageProviderFactory.java Creates counting provider instances.
tests/​custom-providers/​src/​main/​java/​org/​keycloak/​tests/​providers/​federation/​CountingUserStorageProvider.java Supplies in-memory users and tracks lookup calls.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​model/​UserCacheQueryTest.java Tests query caching and exclusion behavior across sessions.
model/​infinispan/​src/​main/​java/​org/​keycloak/​models/​cache/​infinispan/​UserCacheSession.java Caches matching username/email queries on the managed-user path.

Review effort: Balanced

@sguilhen sguilhen 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.

The proposed fix looks correct: cacheUserQuery reuses the same UserAdapter/lifespan gating as the existing non-managed path, and the added realm-id + username/email match guards prevent caching a stale query if the managed user no longer matches the lookup key (e.g. after a rename).

Looks good to me.

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.

UserCacheSession does not cache the username/email query when the user is already managed in the session

3 participants