Repository navigation
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved authorization gaps allow membership removal without rechecking current permissions and recursive deletion of descendant groups owned by another provider.
6 open issues
Verify ownership of all descendant groups before deletion · New Recheck authorization before removing claimed memberships · New Skip retained claims whose memberships were removed · New Lock membership before claim to prevent deadlocks · New Route schema-root member additions through claims handling · New Include the new group ID in POST membership event paths · New
What changed in this PR
Adds experimental, opt-in per-client group membership tracking to Keycloak’s SCIM API, enabling full-list updates from providers such as Okta without removing memberships managed by other clients or administrators.
Changes:
- Adds feature and realm switches, plus persistent membership claims, origins, and group ownership.
- Routes SCIM membership writes and reads through client-specific claims, restricts user-side membership changes, and records creation events.
- Documents the feature and adds integration coverage for shared groups, concurrency, permissions, and disabled behavior.
| File | Description |
|---|---|
| scim/tests/base/src/test/java/org/keycloak/tests/scim/tck/GroupMembershipClaimsTest.java | Tests membership tracking, concurrent updates, reads, and events. |
| scim/tests/base/src/test/java/org/keycloak/tests/scim/tck/GroupMembershipClaimsServerConfig.java | Enables the experimental feature for tests. |
| scim/tests/base/src/test/java/org/keycloak/tests/scim/tck/GroupMembershipClaimsRealmConfig.java | Enables claims in the test realm. |
| scim/tests/base/src/test/java/org/keycloak/tests/scim/tck/GroupMembershipClaimsFeatureOffTest.java | Tests behavior with the feature disabled. |
| scim/tests/base/src/test/java/org/keycloak/tests/scim/tck/GroupMembershipClaimsBoundaryTest.java | Tests user-write restrictions and group ownership. |
| scim/services/src/main/java/org/keycloak/scim/services/ScimResourceTypeResource.java | Emits membership events after resource creation. |
| scim/model/src/main/java/org/keycloak/scim/model/user/UserCoreModelSchema.java | Restricts user-side membership writes in claims mode. |
| scim/model/src/main/java/org/keycloak/scim/model/group/GroupResourceTypeProvider.java | Integrates claims into group writes, reads, and deletion. |
| scim/model/src/main/java/org/keycloak/scim/model/group/GroupMembershipClaimsMode.java | Checks feature and realm switches. |
| scim/model/src/main/java/org/keycloak/scim/model/group/GroupMembershipClaims.java | Implements claim reconciliation, ownership, and locking. |
| scim/model/src/main/java/org/keycloak/scim/model/group/GroupCoreModelSchema.java | Supports claimed-member visibility and change recording. |
| scim/core/src/main/java/org/keycloak/scim/resource/spi/ScimResourceTypeProvider.java | Adds a creation-time membership event hook. |
| model/jpa/src/main/resources/META-INF/jpa-changelog-27.0.0.xml | Creates tracking tables, constraints, and indexes. |
| model/jpa/src/main/java/org/keycloak/models/jpa/entities/ScimGroupOwnerEntity.java | Maps group ownership records. |
| model/jpa/src/main/java/org/keycloak/models/jpa/entities/ScimGroupMembershipOriginEntity.java | Maps SCIM-created membership markers. |
| model/jpa/src/main/java/org/keycloak/models/jpa/entities/ScimGroupMembershipClaimEntity.java | Maps per-client membership claims. |
| docs/documentation/server_admin/topics/scim/managing-users.adoc | Documents user membership write restrictions. |
| docs/documentation/server_admin/topics/scim/managing-groups.adoc | Documents activation, behavior, and limitations. |
| common/src/main/java/org/keycloak/common/Profile.java | Registers the experimental feature. |
Review effort: Balanced
…he group Some identity providers send a group's full member list on every update, with PUT. Okta applications built with the App Integration Wizard work this way and cannot be switched to PATCH. Keycloak refuses members on PUT, so these providers cannot manage group membership at all. This change lets the SCIM client that creates a group own it. The owner can then send full member lists. It sits behind two switches, and both must be on: the experimental feature scim-group-membership-claims, which requires scim-api, and the realm attribute scimGroupMembershipClaims set to true. With either switch off, SCIM behaves exactly as before. With both on: - The client that creates a group with POST /Groups owns it, and the POST may include members. The owner is stored by the client's clientId in the new SCIM_GROUP_OWNER table. The row is removed with the group, and kept when the client is deleted, so a client created again with the same clientId owns its groups again. - The owner can send the full member list with PUT, or with a PATCH that replaces members, also with no path or with the Group schema URN as the path. Keycloak adds the listed users who are not members and removes the members who are not listed. PATCH add and remove keep working, including a remove that lists the members in its value, as Microsoft Entra ID sends it. - Service accounts and administrators are never removed by the owner. A full list that leaves one out keeps that member and applies the rest. Naming one in an add or remove, or adding one, is refused as before. - Every member is checked before anything changes. A user that does not exist rejects the whole request. Requests for the same group are serialized with a row lock on the group. - Other SCIM clients get 403 on PUT, PATCH and DELETE of an owned group, and on DELETE of a group that has another client's group below it. - A write to a user's groups that would add or remove a membership of an owned group is refused with 400 and scimType mutability. - A read of an owned group shows every member without being asked, so that a provider that rebuilds its next PUT from a read keeps its members. - Groups that no SCIM client owns behave as before, and never get an owner. Administrators can still change an owned group's members through the Admin Console and the Admin REST API. The owner's next full list overwrites that change, except for service accounts and administrators. Blocking those edits is left to a later change. Closes keycloak#55341 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Prasad Rahatekar <83812676+Prasad484@users.noreply.github.com>
Prasad484
force-pushed
the
scim-group-membership-okta-entra
branch
from
November 19, 2026 14:10
f1105ab to
73c4ac3
Compare
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Realm export/import loses group ownership and permits unauthorized modifications, while stale membership reads and inconsistent lock ordering can cause incorrect concurrent updates or deadlocks.
4 open issues
6 resolved since last review
Recheck authorization before removing claimed memberships Verify ownership of all descendant groups before deletion Include the new group ID in POST membership event paths Route schema-root member additions through claims handling Lock membership before claim to prevent deadlocks Skip retained claims whose memberships were removed
Review effort: Balanced
Comment on lines
+109
to
+111
| void recordOwner(GroupModel group, String owner) { | ||
| em.persist(new ScimGroupOwnerEntity(group.getId(), owner)); | ||
| em.flush(); |
| */ | ||
| void lock(GroupModel group) { | ||
| em.flush(); | ||
| GroupEntity entity = em.find(GroupEntity.class, group.getId(), LockModeType.PESSIMISTIC_WRITE); |
Comment on lines
+189
to
+193
| Set<String> currentMembers(GroupModel group) { | ||
| RealmModel realm = session.getContext().getRealm(); | ||
| return session.users().getGroupMembersStream(realm, group) | ||
| .map(UserModel::getId) | ||
| .collect(Collectors.toCollection(LinkedHashSet::new)); |
Comment on lines
+376
to
+388
| private Set<String> storedMembers(GroupModel group) { | ||
| List<String> ids = em.createQuery("select m.user.id from UserGroupMembershipEntity m where m.groupId = :groupId", String.class) | ||
| .setParameter("groupId", group.getId()) | ||
| .getResultList(); | ||
| return new HashSet<>(ids); | ||
| } | ||
|
|
||
| private boolean isStored(String groupId, String userId) { | ||
| return em.createQuery("select count(m) from UserGroupMembershipEntity m where m.groupId = :groupId and m.user.id = :userId", Long.class) | ||
| .setParameter("groupId", groupId) | ||
| .setParameter("userId", userId) | ||
| .getSingleResult() > 0; | ||
| } |
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 #55341
Why
Okta applications built with the App Integration Wizard send every group change after the first push as a full-list
PUT /Groups/{id}, and they cannot be switched toPATCH. Keycloak refusesmembersonPUTtoday, so those applications cannot push group membership. AcceptingPUTas a plain replace for every caller would let one SCIM client remove members another client added. The proposal and its open questions are in #55340.What this adds
An experimental feature
scim-group-membership-claims, which also needs the realm attributescimGroupMembershipClaimsset totrue. With either one off, nothing changes.When both are on, the SCIM client that creates a group owns it, and only that client changes the group's members:
POST /Groupsmay includemembers. The group is created with them, and the calling client becomes its owner. The calling client is the client the access token was issued to.PUT, or with aPATCHthat replacesmembers, also with no path or with the Group schema URN as the path. Keycloak adds listed users who are not members and removes members who are not listed.PATCHaddandremovework too, including aremovethat lists the members in itsvalue, as Microsoft Entra ID sends it.addorremove, or adding one, is refused as before.PUT,PATCHandDELETEof an owned group, and onDELETEof a group with another client's group below it.groupsthat would add or remove a membership of an owned group is refused with a 400 andscimType: "mutability", as RFC 7643 section 4.1.2 describes.attributes=members. Okta rebuilds its nextPUTfrom a read, and a read without members would make thatPUTempty the group.Decisions
jpa-changelog-27.0.0.xml:SCIM_GROUP_OWNER(group, client ID), with a foreign key to the group that cascades on delete. There is no foreign key to the client, so the owner is kept when the client is deleted, and a client created again with the same client ID owns its groups again. A client whose client ID is renamed loses its groups.Not changed
Realms without the feature and the realm attribute behave exactly as before, including
PATCHreplaceonmembers(#52752) and thePUTrefusal. Administrators can still change an owned group's members through the Admin Console and the Admin REST API. The owner's next full list overwrites that change, except for service accounts and administrators, and the documentation says so. Refusing those edits, and making identity provider and LDAP group mappers skip owned groups, are planned as separate changes. This change does not depend on #55310.Review focus
GroupOwnership(the owner record, the full-list plan, locking), the changes inGroupResourceTypeProviderthat route owner and non-owner writes, thegroupswrite check inUserCoreModelSchema, and the changelog entry.Local validation (main 9492138)
quarkus/dist, which the test server is unpacked from),./mvnw -pl scim/core,scim/tests/base testpasses on the default H2 database: 51 unit tests and 335 integration tests, 2 skipped (both already@Disabled). The new tests areGroupOwnershipTest15,GroupOwnershipBoundaryTest10,GroupOwnershipFeatureOffTest5 andGroupOwnershipAttributeOffTest5.GroupTest(38),UserTest(106, 2 skipped) andAdminGroupProtectionTest(23) also pass on PostgreSQL 18, where the row lock on the group matters most../mvnw -Pspotless spotless:checkpasses for every module this change touches:common,model/jpa,scim/core,scim/model,scim/servicesandscim/tests/base.An earlier version of this PR tracked members per SCIM client. It was run against a real Okta wizard app. This version has not yet been run against Okta.
AI assistance: this change was prepared with Claude Code, an AI coding agent. I have reviewed it and will handle the review.
🤖 Generated with Claude Code