Skip to content

Avoid per-user organization membership lookups when no organization is disabled - #55252

Open
vivekksk wants to merge 2 commits into
keycloak:mainfrom
vivekksk:issue-46681-org-readonly-member
Open

vivekksk wants to merge 2 commits into
keycloak:mainfrom
vivekksk:issue-46681-org-readonly-member

Conversation

@vivekksk

@vivekksk vivekksk commented Nov 16, 2026 •

Copy link
Copy Markdown

Closes #46681

Summary

isReadOnlyOrganizationMember runs on every user lookup: user cache load and validation, GET /users, organization member listing, and the authorize, token and refresh requests. For each organization the user belongs to, it ran the managed-membership check, a database round trip, before the cheap isEnabled() check. An unmanaged member of N organizations therefore paid N queries on every request, even when every organization was enabled.

 isReadOnlyOrganizationMember(user)        // Organizations + UserStorageManager copy
   if feature off / no organizations: return false
+  if organizations enabled and !provider.hasDisabledOrganizations()
+    return false                          // nobody can be read-only
   getByMember(user).anyMatch(org ->
-    (enabled && org.isManaged(user) && !org.isEnabled()) || (!enabled && org.isManaged(user)))
+    (!enabled || !org.isEnabled()) && org.isManaged(user))   // same result, cheap check first

hasDisabledOrganizations() follows the existing hasOrganizations() pattern:

OrganizationProvider#hasDisabledOrganizations     default: getAllStream().anyMatch(!enabled)
  JpaOrganizationProvider                         named query existsDisabledByRealm, LIMIT 1
  InfinispanOrganizationProvider                  CachedExists in the realm cache, key <realm>.org.disabled.exists
                                                  invalidated on organization create, update (incl. enable/disable) and remove

Evidence

Tests added in tests/base:

  • OrganizationCacheTest#testHasDisabledOrganizations (@DatabaseTest): checks the JPA and cached answers as an organization is disabled, re-enabled, created disabled and removed, and that the cached entry is invalidated after each change.

  • OrganizationMemberTest#testManagedMemberEnabledStateFollowsOrganizationEnabledState: a managed member is reported disabled, enabled and disabled again as the organization is toggled. Each step is checked through organization members, user search and get-by-id, so stale state would be caught.

  • OrganizationMemberTest#testManagedMemberEnabledWhenAnotherOrganizationIsDisabled: a managed member of an enabled organization who is also an unmanaged member of a disabled organization stays enabled. This covers the reordered predicate.

  • Before: the issue reports O(N) queries joining KEYCLOAK_GROUP.TYPE=1 per listed user. A later comment on 26.7.5 reports about 3.3 s per authorize, token and refresh request for a user in about 1,100 organizations.

  • After: the new tests and the existing testGetAllDisabledOrganization, testGetAllDisabledOrganizationProvider and testMembersCount pass locally. The full org.keycloak.tests.organization package also passes locally (distribution server, H2, JDK 21): 498 tests in 32 classes, 0 failures, 0 errors, 0 skipped.

Benchmark against the scenario from the issue (1,101 organizations, unmanaged members, Postgres): for a member of all organizations, adding or removing a member drops from about 10 s to under 50 ms, one member-listing row from about 4.5 s to 6 ms, and authorize, code-to-token and refresh from about 1.1–1.3 s to 9 ms each. Results are similar when one unrelated organization is disabled. Full setup and tables: #46681 (comment)

Merge Danger

Door: two-way

No schema change and no data migration. The new SPI method has a default implementation, so custom OrganizationProvider implementations keep compiling and working.

Blast Radius: read-only member detection

If the new cache entry were ever stale, managed members of a disabled organization could appear enabled, or the reverse, until the realm cache entry is invalidated. The entry is invalidated in the same places as the existing organization entries (registerOrganizationInvalidation, registerCountInvalidation), and the tests cover each transition.

🤖 Generated with Claude Code

…s disabled

Organizations.isReadOnlyOrganizationMember (and its copy in
UserStorageManager) runs for every user lookup, including user listing,
organization member listing, token and refresh requests. It walked all
organizations of the user and evaluated the managed membership check,
a database round trip, before the cheap enabled check, so unmanaged members
of many organizations paid one query per organization on every request.

- Add OrganizationProvider#hasDisabledOrganizations, backed by a single
  query in JPA and cached in the realm cache by the Infinispan provider.
  The cached entry is invalidated when an organization is created, updated
  or removed.
- Return early when organizations are enabled and none is disabled, as no
  member can be read-only in that case.
- Otherwise check the organization's enabled state before the managed
  membership check.

Closes keycloak#46681

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Vivek Shanmughan <6814487+vivekksk@users.noreply.github.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

A critical cache race can expose an uncommitted organization enablement to concurrent requests, incorrectly treating managed members as enabled even if the transaction rolls back.

1 open issue
What changed in this PR

Addresses #46681 by skipping per-user organization membership checks when organizations are enabled realm-wide and none is disabled.

Changes:

  • Adds a disabled-organization existence check with JPA and cached implementations.
  • Updates both read-only member checks to short-circuit and evaluate enabled state before managed membership.
  • Adds tests for cache invalidation and managed-user enabled-state transitions.
File Description
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​organization/​member/​OrganizationMemberTest.java Tests enabled-state transitions and mixed managed/unmanaged memberships.
tests/​base/​src/​test/​java/​org/​keycloak/​tests/​organization/​cache/​OrganizationCacheTest.java Tests disabled-organization detection and cache invalidation.
services/​src/​main/​java/​org/​keycloak/​organization/​utils/​Organizations.java Adds the fast path to shared read-only member detection.
server-spi/​src/​main/​java/​org/​keycloak/​organization/​OrganizationProvider.java Adds a default disabled-organization existence check.
model/​storage-private/​src/​main/​java/​org/​keycloak/​storage/​UserStorageManager.java Applies the same optimization to storage-level user lookups.
model/​jpa/​src/​main/​java/​org/​keycloak/​organization/​jpa/​JpaOrganizationProvider.java Implements a result-limited existence query.
model/​jpa/​src/​main/​java/​org/​keycloak/​models/​jpa/​entities/​OrganizationEntity.java Defines the disabled-organization named query.
model/​infinispan/​src/​main/​java/​org/​keycloak/​models/​cache/​infinispan/​organization/​InfinispanOrganizationProvider.java Caches the realm-level result and registers invalidation on organization changes.

Review effort: Balanced

If an organization was created, updated or removed in the current
transaction, the realm cache invalidation is only applied on transaction
completion. Loading the flag on a cold cache in that transaction published
a value based on uncommitted changes to other transactions until then.
Read it from the database without caching in that case, as getByAlias does.

Closes keycloak#46681

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Vivek Shanmughan <6814487+vivekksk@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 16, 2026 19:32

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 optimization that avoids unnecessary organization-membership lookups.

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.

Performance regression: /admin/realms/{realm}/users triggers per-user org membership lookup (N+1 KEYCLOAK_GROUP.TYPE=1) even when no disabled orgs exist

2 participants