Repository navigation
Batch composite-role expansion to avoid an N+1 of getChildRoles on the cache-miss path - #50370
Conversation
RoleUtils.expandCompositeRolesStream gated each node on isComposite() before calling getCompositesStream(). On the JPA (cache-miss) path both run the getChildRoles named query -- and a FlushMode.AUTO flush before each -- so every composite node issued two getChildRoles round-trips while expanding the tree. getCompositesStream() already yields an empty stream for non-composite roles, making the pre-check redundant. Fetch the composites directly instead. Behaviour is unchanged (verified by RoleUtilsCompositeExpansionTest: identical expansion, isComposite() no longer called, cycles still terminate). On a 10-node composite chain the deterministic query-count model test (CompositeRoleExpansionQueryCountTest, jpa profile) shows getChildRoles executions drop from 19 to 10 -- the saving equals the number of composite nodes (C) per expansion. Signed-off-by: Hüseyin Akdoğan <huseyin@keymate.io>
The composite-role walk in RoleUtils issues one getChildRoles query per role node. On a cache miss this is an N+1 over the whole role tree, each query preceded by a FlushMode.AUTO flush. Add a bulk primitive RoleProvider.getCompositeRolesStream(realm, parentIds) -- default resolves each parent individually, JpaRealmProvider overrides it with a single getChildRolesFromParentIds named query (IN clause) that hydrates the child RoleEntity rows so the follow-up getRoleById calls are served from the persistence context. RoleStorageManager delegates to local storage. RoleUtils.expandCompositeRoles(session, realm, roles) uses it to expand the tree one breadth-first level at a time: one query per level instead of one per node, while preserving the visited-set cycle protection and dedup. CompositeRoleExpansionQueryCountTest (jpa profile) proves it on a 31-node wide tree (root -> 5 -> 25): the per-node walk issues 31 getChildRoles queries, level-wise batching issues 3 (one per depth), and both produce the same expanded role set. Signed-off-by: Hüseyin Akdoğan <huseyin@keymate.io>
Route the composite-role expansion on the token and permission paths through the level-wise batched RoleUtils variants so the N+1 reduction reaches the flows the load test exercises. Add session-aware RoleUtils.getDeepUserRoleMappings(session, realm, user) and expandCompositeRolesStream(session, realm, roles), and switch: - TokenManager.getAccess: add a session-aware overload; the existing (UserModel, ClientModel, Stream) signature is kept and delegates to the per-node expansion, so the public API is unchanged, - DefaultClientSessionContext client-scope role expansion and user roles, - RolePolicyProvider (admin fine-grained permissions) deep user role mappings. The non-session methods are kept for callers without a session. Behaviour is unchanged: the batched expansion returns the same role set as the per-node walk (CompositeRoleExpansionQueryCountTest); a custom RoleProvider that does not override getCompositeRolesStream still resolves composites via the interface default (RoleProviderCompositeDefaultTest); RoleModelTest and CompositeRolesModelTest pass. Signed-off-by: Hüseyin Akdoğan <huseyin@keymate.io>
There was a problem hiding this comment.
Pull request overview
This PR optimizes composite-role expansion on the cache-miss path by removing a redundant per-role isComposite() pre-query and introducing a breadth-first, level-wise batched expansion API that allows JPA to resolve composite children with an IN query per level (O(tree depth) queries) instead of one query per role (O(tree size)).
Changes:
- Remove
isComposite()gating during per-node expansion to avoid an extragetChildRolesquery (and associated auto-flush) per composite role. - Add a bulk composite expansion path (
RoleProvider#getCompositeRolesStream+ newRoleUtilsoverloads) and wire it into token/scope/access resolution and admin authz role policy evaluation. - Add tests validating expansion correctness and (for JPA) reduced query counts.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| testsuite/model/src/test/java/org/keycloak/testsuite/model/role/CompositeRoleExpansionQueryCountTest.java | Adds a JPA/Hibernate-statistics-based test to assert query-count reduction for batched expansion. |
| services/src/main/java/org/keycloak/services/util/DefaultClientSessionContext.java | Switches client-scope role expansion and access resolution to session/realm-aware bulk expansion. |
| services/src/main/java/org/keycloak/services/resources/account/AccountConsole.java | Uses the new TokenManager.getAccess(session, ...) overload for bulk expansion. |
| services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java | Adds a session-aware getAccess overload and factors expansion via an injected function. |
| server-spi/src/test/java/org/keycloak/models/utils/RoleUtilsCompositeExpansionTest.java | Adds unit coverage asserting expansion correctness and that isComposite() is not called. |
| server-spi/src/test/java/org/keycloak/models/RoleProviderCompositeDefaultTest.java | Adds unit coverage for RoleProvider#getCompositeRolesStream default behavior (dedupe across parents). |
| server-spi/src/main/java/org/keycloak/models/utils/RoleUtils.java | Removes redundant isComposite() pre-check and adds bulk expansion APIs for session/realm-aware batching. |
| server-spi/src/main/java/org/keycloak/models/RoleProvider.java | Introduces default bulk API getCompositeRolesStream(realm, parentRoleIds) for batched child-role lookup. |
| model/storage-private/src/main/java/org/keycloak/storage/RoleStorageManager.java | Delegates the new bulk composite lookup API to local storage. |
| model/jpa/src/main/java/org/keycloak/models/jpa/JpaRealmProvider.java | Overrides bulk composite lookup with a single IN named query per level. |
| model/jpa/src/main/java/org/keycloak/models/jpa/entities/RoleEntity.java | Adds getChildRolesFromParentIds named query for batched child-role resolution. |
| authz/policy/common/src/main/java/org/keycloak/authorization/policy/provider/role/RolePolicyProvider.java | Switches deep role mapping resolution to the new bulk session/realm-aware API. |
- CompositeRoleExpansionQueryCountTest: require JpaConnectionProvider so the test is skipped rather than failing with an NPE on non-JPA backends (it reads Hibernate statistics via JpaConnectionProvider). - RoleProviderCompositeDefaultTest: pass a non-null RealmModel (honoring the getCompositeRolesStream contract) instead of null. Signed-off-by: Hüseyin Akdoğan <huseyin@keymate.io>
Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
…er Keycloak strategy Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
Signed-off-by: Alexander Schwartz <alexander.schwartz@ibm.com>
- RoleUtils.expandCompositeRoles: guard against null KeycloakSession by falling back to per-role stack expansion when no session context is available (fixes r3488823474) - RoleStorageManager.getCompositeRolesStream: split parent IDs into local and external; external (federated) IDs fall back to per-role getRoleById + getCompositesStream instead of being silently dropped (fixes r3488823485) - RealmCacheSession.getCompositeRolesStream: prefix cache key with realm ID to prevent cross-realm key collisions; use String.join for a more predictable key format (fixes r3488823491) - RealmCacheSession.getCompositeRolesStream: null-check the result of cache.get(parentId, CachedRole.class) before dereferencing it to prevent NPE on evicted entries (fixes r3488823493) - CompositeRoleExpansionQueryCountTest.countQueries: save and restore Hibernate statistics enabled state to avoid affecting other tests (fixes r3488823497) - CompositeRoleExpansionQueryCountTest: rename droppingIsCompositePreQueryHalvesGetChildRolesOnCompositeNodes to chainWalkIssuesOneQueryPerBreadthFirstLevel (fixes r3488823503)
|
@hakdogan - thank you for this PR! I like the approach. In some additional commits, I've rolled back some of the API changes to keep the original API where possible, and to pull the session from the context. I've also moved the integration test to the new testsuite. We usually rely on integration tests, when testing models, so I remove one of the unit tests that tested models once it didn't work any more when I started to use the session. We try to no longer add new model tests. Due to that, I moved the model test to the new testsuite. I've also added caching to the newly added method, so that it does not touch the database all the time. Let's see what the CI reports about this. Let me know if think these changes are valid. Thanks! |
|
Thanks @ahus1, I really appreciate you taking this forward. I went through the changes and from our side they are valid and a clear improvement over what I opened. Keeping the original API and adding the caching layer make the result stronger, the cache-miss N+1 stays resolved, and the reworked integration test is a solid regression guard. Thanks again for the careful review and the extra work on it. |
|
@shawkins / @pedroigor - I would like to merge this PR for the upcoming 26.7 release. Do you have any second thoughts on this or other review comments before I merge? Thanks! |
Closes #50369
Problem
On the cache-miss path (realm/user cache disabled, cold cache, or after invalidation), resolving a user's effective roles dominates Keycloak CPU. Expanding the composite-role tree issues one
getChildRolesquery per role (an N+1), and underFlushMode.AUTOeach query is preceded by a full persistence-context auto-flush, so the cost isO(roles in the tree) × auto-flush. Profiling shows the composite-expansion path accounting for the majority of CPU and a large multiplier on database queries (before/after numbers in #50369).Cause
RoleUtils.expandCompositeRolesStreamwalks the tree node by node. On the JPARoleAdapterevery node runs thegetChildRolesnamed query — composite nodes twice, once forisComposite()and once forgetCompositesStream()— each preceded by an auto-flush. This is reached on the token/permission paths viaTokenManager.getAccess,DefaultClientSessionContext, and the admin fine-grainedRolePolicyProvider(throughgetDeepUserRoleMappings/expandCompositeRolesStream).This is distinct from #46622, which addressed the startup / cache-warm scan;
FlushMode.AUTO(#10411 / #10623) is intentional, so the fix targets the N+1 multiplier rather than the flush mode.Fix
Drop the redundant pre-query in
expandCompositeRolesStream: fetch composites directly instead of gating onisComposite()first —getCompositesStream()already returns an empty stream for non-composite roles — removing onegetChildRoles(and its auto-flush) per composite node.Batch the walk with a level-wise
IN: a newdefaultmethodRoleProvider.getCompositeRolesStream(RealmModel, Set<String> parentRoleIds), overridden inJpaRealmProviderwith a singlegetChildRolesFromParentIdsINquery (and delegated byRoleStorageManager); a newRoleUtils.expandCompositeRoles(KeycloakSession, RealmModel, Set<RoleModel>)expands one breadth-first level per query (O(tree depth)instead ofO(tree size)), preserving cycle protection and de-duplication. The token/permission paths use the session-aware variants.Kept intentionally compatible:
RoleProvider.getCompositeRolesStreamis a default method — custom / non-JPA providers run unchanged (unbatched) and can opt in by overriding it;RoleUtilsadditions are new overloads; existing methods are untouched;TokenManager.getAccesskeeps its existing(UserModel, ClientModel, Stream)signature (delegating to the per-node expansion); the batched path is a new(KeycloakSession, …)overload — no public API break;@NamedQueryis metadata only).Testing
RoleUtilsCompositeExpansionTest(server-spi) — expansion result unchanged,isComposite()no longer called during the walk, cyclic graphs still terminate.RoleProviderCompositeDefaultTest(server-spi) — a customRoleProviderthat does not overridegetCompositeRolesStreamstill resolves composites correctly (de-duplicated) via the interface default.CompositeRoleExpansionQueryCountTest(testsuite/model,-Pjpa) — counts actualgetChildRolesSQL executions: on a wide tree (31 roles, depth 3) the node-by-node walk issues 31 queries, the batched w 8000 alk 3, with the same resolved set.RoleModelTestandCompositeRolesModelTestremain green.