Skip to content

Accept a SCIM group PUT with members from the SCIM client that owns the group - #55342

Open
Prasad484 wants to merge 1 commit into
keycloak:mainfrom
Prasad484:scim-group-membership-okta-entra
Open

Prasad484 wants to merge 1 commit into
keycloak:mainfrom
Prasad484:scim-group-membership-okta-entra

Conversation

@Prasad484

@Prasad484 Prasad484 commented Nov 19, 2026 •

Copy link
Copy Markdown

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 to PATCH. Keycloak refuses members on PUT today, so those applications cannot push group membership. Accepting PUT as 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 attribute scimGroupMembershipClaims set to true. 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 /Groups may include members. 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.
  • The owner can send a 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 listed users who are not members and removes members who are not listed. PATCH add and remove work too, including a remove that lists the members in its value, as Microsoft Entra ID sends it.
  • Service accounts and administrators are never removed by a full list. A 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, so a user that does not exist rejects the whole request.
  • Another SCIM client gets a 403 on PUT, PATCH and DELETE of an owned group, and on DELETE of a group with 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 a 400 and scimType: "mutability", as RFC 7643 section 4.1.2 describes.
  • A read of an owned group shows every member without attributes=members. Okta rebuilds its next PUT from a read, and a read without members would make that PUT empty the group.
  • Groups that no SCIM client created behave as before and never get an owner.

Decisions

  • Storage is one table in 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.
  • Requests that change the same group take a lock on the group row and run one after the other. An administrator who removes a member at the same time as the owner's list drops it is handled: both succeed.
  • Memberships stored outside the Keycloak database, for example by an LDAP group mapper, cannot be tracked. A request that would remove one is refused before anything changes. An add to one is only found after the write, so the request fails but the external store keeps the change, as the documentation says.
  • A 403 can now carry a message, so another client is told the group is managed by another SCIM client.

Not changed

Realms without the feature and the realm attribute behave exactly as before, including PATCH replace on members (#52752) and the PUT refusal. 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 in GroupResourceTypeProvider that route owner and non-owner writes, the groups write check in UserCoreModelSchema, and the changelog entry.

Local validation (main 9492138)

  • With the distribution rebuilt from this branch (quarkus/dist, which the test server is unpacked from), ./mvnw -pl scim/core,scim/tests/base test passes on the default H2 database: 51 unit tests and 335 integration tests, 2 skipped (both already @Disabled). The new tests are GroupOwnershipTest 15, GroupOwnershipBoundaryTest 10, GroupOwnershipFeatureOffTest 5 and GroupOwnershipAttributeOffTest 5.
  • The ownership tests, GroupTest (38), UserTest (106, 2 skipped) and AdminGroupProtectionTest (23) also pass on PostgreSQL 18, where the row lock on the group matters most.
  • ./mvnw -Pspotless spotless:check passes for every module this change touches: common, model/jpa, scim/core, scim/model, scim/services and scim/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

@Prasad484
Prasad484 marked this pull request as ready for review November 19, 2026 03:58
@Prasad484
Prasad484 requested a review from a team as a code owner November 19, 2026 03:58
Copilot AI balanced review requested due to automatic review settings November 19, 2026 03:58

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

Unresolved authorization gaps allow membership removal without rechecking current permissions and recursive deletion of descendant groups owned by another provider.

6 open issues
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
Prasad484 force-pushed the scim-group-membership-okta-entra branch from f1105ab to 73c4ac3 Compare November 19, 2026 14:10
Copilot AI balanced review requested due to automatic review settings November 19, 2026 14:10
@Prasad484 Prasad484 changed the title Accept a SCIM group PUT with members by tracking members per SCIM client Accept a SCIM group PUT with members from the SCIM client that owns the group Nov 19, 2026

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.

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;
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SCIM: accept a group's full member list on PUT from the SCIM client that owns the group

2 participants