SCIM Group Member Resource Type Extension

Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/Zollnerd/scim-group-membership.

Introduction The System for Cross-domain Identity Management (SCIM) 2.0 protocol RFC7643 is widely used for automating the provisioning of identities across disparate systems. While SCIM excels at managing individual User and Group resources, its design for representing relationships, specifically group memberships, encounters significant performance bottlenecks in large-scale enterprise environments. Currently, the "members" attribute of a Group resource is a multi-valued attribute. Because SCIM only supports paginating resources, a client requesting a Group resource must receive the entire list of group members in a single HTTP response. For a group with one million members, an HTTP response can reach approximately 200MB in size. These large payloads create several critical failure points including memory pressure and network timeouts. This document proposes the "GroupMember" resource type. By treating a membership as a first-class, top-level resource, Service Providers can leverage existing SCIM query parameters including filter, count, and multiple pagination methods, allowing them to implement a scaleable and reliable interface for managing groups of any size.

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

The GroupMember Resource This section defines the GroupMember resource, which represents a single membership relationship between a SCIM Group and a member. By representing each membership as a distinct, top-level resource, Service Providers can manage group memberships individually, allowing for pagination, filtering, and other operations at scale. A GroupMember resource represents a direct membership only. Indirect memberships, as defined in Section 4.1.2, MUST NOT be represented as GroupMember resources.

Resource Properties The GroupMember resource is defined by the following properties:

schemas: A multi-valued attribute that contains the SCIM schema URNs for this resource. The URN for the GroupMember resource's core schema is urn:ietf:params:scim:schemas:core:2.0:GroupMember. This is a REQUIRED attribute. This attribute is a common attribute inherited from .

id: A unique identifier for the GroupMember resource, generated by the Service Provider. This is a REQUIRED, read-only attribute. Clients MUST treat this value as opaque. The id serves as the stable identifier for a membership link — it uniquely identifies the relationship between a specific group and a specific member, and is the value used to address the resource at the /GroupMembers/{id} URI. This attribute is a common attribute inherited from .

group

A complex attribute that provides a reference to the parent Group resource. This attribute contains the following sub-attributes:

value: The id of the referenced Group resource. REQUIRED.
$ref: The URI of the referenced Group resource. Read-only.
display: A human-readable name for the referenced Group resource, generally corresponding to the Group's displayName attribute. Read-only.

member

A complex attribute that provides a reference to the member resource, which can be a User, another Group, or any other resource type that can be a member of a group. This attribute contains the following sub-attributes:

value: The id of the referenced member resource. REQUIRED.
$ref: The URI of the referenced member resource. Read-only.
type: A string that specifies the resource type of the member, e.g., "User" or "Group". Read-only.
display: A human-readable name for the referenced member resource, generally corresponding to the member's displayName attribute. Read-only.

meta: A complex attribute containing metadata about the resource. This includes the resourceType (which MUST be "GroupMember"), created, lastModified, and location attributes. This is a REQUIRED, read-only attribute. This attribute is a common attribute inherited from .

If a Service Provider's implementation does not support creating or deleting GroupMember resources, all attributes in the schema definition returned from /Schemas MUST have their mutability property set to readOnly.

JSON Representation The following is an example of a GroupMember resource in JSON format. This example represents the membership of a User in a Group. ($ref values truncated for formatting purposes):

Resource Type Representation The Service Provider's ResourceType schema, available at the /ResourceTypes endpoint, MUST include an entry for "GroupMember". Example ResourceType entry:

membersMetadata Group Schema Extension To prevent ambiguity and provide a clear path for clients, this specification also defines an extension schema for the Group resource. This extension introduces a new complex attribute, membersMetadata, which signals how group memberships are managed and provides metadata about those memberships. When a Service Provider supports the /GroupMembers endpoint, it SHOULD include the membersMetadata attribute on Group resources to declare its membership management policy for that group. The schema URN for the membersMetadata schema extension is urn:ietf:params:scim:schemas:extension:groupMembers:2.0:Group

The membersMetadata Attribute The membersMetadata attribute is a complex attribute with the following sub-attributes:

policy

A REQUIRED string that specifies how membership for this group is represented. It MUST have one of the following values:

inline: Indicates that this group's members are fully represented in the members attribute. Clients SHOULD NOT use the /GroupMembers endpoint for this group.
external: Indicates that this group's members are managed exclusively via the /GroupMembers endpoint. The members attribute MUST be omitted from this Group resource representation.
hybrid: Indicates that the Service Provider MAY return members in the members attribute, but the canonical method for managing memberships is via /GroupMembers. Clients SHOULD prefer using the /GroupMembers endpoint for reliability and scale.

ref: A REQUIRED URI that a client can use to query for the group's members. It MUST be the URI of the /GroupMembers endpoint with a pre-populated filter for the current group's ID. Its format is [GroupMembers_Endpoint]?filter=group.value eq "[Group_ID]".

memberCount: An OPTIONAL non-negative integer indicating the total number of members in the group.

allowedMemberTypes: An OPTIONAL multi-valued attribute containing a list of strings that specify the resource types (resourceType) of members allowed in this group.

Example Group Resources

Example of an "External" Policy The following is a Group with a large number of members. The policy is "external", the members attribute is absent, and the client is directed to use the ref URI.

Example of a "Hybrid" Policy The following is a Group with a small number of members. The policy is "hybrid", indicating that while the members are included inline for convenience, clients should still prefer using the /GroupMembers endpoint for management operations.

Managing GroupMember Resources This section describes how GroupMember resources are managed using the SCIM protocol. A GroupMember is a simple resource that represents a linkage between a group and a member. As such, a membership can only be created, retrieved, or deleted. Updating a membership serves little practical value, as changing the group or the member would fundamentally represent a new membership, not a modification of the existing one. Therefore, a Service Provider that supports this specification MUST only support the POST, GET, and DELETE methods for this resource type. Service Providers MAY also support management of group members through the existing members attribute of the Group resource as defined in for the purpose of backwards compatibility with existing clients. However, when adding or removing members from a group that also has GroupMember resources, Service Providers MUST ensure that the state remains consistent across both representations. For example, deleting a GroupMember resource MUST result in the corresponding member being removed from the members array on the Group resource, if that attribute is supported by the Service Provider.

Creating GroupMember Resources (POST) To add a new member to a group, the client sends a POST request to the GroupMembers endpoint. The request body MUST contain a GroupMember resource, specifying the group.value and member.value.

Request: POST /scim/v2/GroupMembers
Response: 201 Created with the full GroupMember resource in the body, including its newly generated id and meta attributes.

A Service Provider MUST ensure that both the group and the member referenced by their ids exist before creating the GroupMember resource. If either the group or the member does not exist, the Service Provider SHOULD return a 400 Bad Request error with a scimType of invalidValue. If the membership already exists, the Service Provider MUST return a 409 Conflict error. Example Request Body: POST /GroupMembers

Retrieving GroupMember Resources (GET) GroupMember resources can be retrieved by sending a GET request to the GroupMembers endpoint. Clients can retrieve an individual resource by its id or a list of resources.

To get a specific membership: GET /scim/v2/GroupMembers/{id}
To get all memberships: GET /scim/v2/GroupMembers

Pagination Service Providers MUST support pagination of GroupMember resources to allow clients to retrieve large sets of memberships in manageable chunks. Index-based Pagination: The startIndex and count query parameters are the primary method for pagination, as defined in .

Example: GET /scim/v2/GroupMembers?startIndex=1&count=1000

Cursor as defined in for improved performance with very large data sets.

Example: GET /scim/v2/GroupMembers?count=1000&cursor=aW5kZXg9MTAx

The response for a paginated request is a ListResponse containing the GroupMember resources for the current page.

Filtering Service Providers MUST support filtering on the group.value and member.value attributes. This enables clients to perform critical queries, such as "find all members of a specific group" or "find all groups a specific user is a member of."

To find all members of a group:: GET /scim/v2/GroupMembers?filter=group.value eq e9e30dba-f08f-4139-944c-2e6949b80b05"

To find all groups for a member:: GET /scim/v2/GroupMembers?filter=member.value eq "2819c223-7f76-453a-919d-413861904646"

Deleting GroupMember Resources (DELETE) To remove a member from a group, the client sends a DELETE request to the URI of the specific GroupMember resource.

Request: DELETE /scim/v2/GroupMembers/{id}
Response: 204 No Content on successful deletion.

Bulk Operations Clients can create and delete multiple GroupMember resources in a single request using the /Bulk endpoint as defined in . This is highly efficient for synchronizing memberships for a group with many changes. The following is an example of a Bulk request that adds two new members and removes one existing member from a group. Example Bulk Request:

Service Provider Considerations This section describes the requirements for Service Providers that implement the GroupMember resource.

Discovering Support for the GroupMember Resource Service Providers that support the GroupMember resource MUST declare this support in their ResourceType and Schema metadata.

Schema Endpoint The Service Provider's Schema definition, available at the /Schemas endpoint, MUST include the full schema definitions for urn:ietf:params:scim:schemas:core:2.0:GroupMember as defined in Section 2.3 of this document.

Impact on the Group Resource As noted in Section 6, a Service Provider MAY continue to support the members attribute on the Group resource for backwards compatibility. When doing so, the Service Provider MUST maintain transactional integrity and consistency between the state of the members attribute and the state of the corresponding GroupMember resources. For example, if a DELETE request to a /GroupMembers/{id} URI is successful, the corresponding member MUST also be removed from the members array of the parent Group resource. Conversely, if a member is removed from a Group via a PATCH request to the /Groups/{id} URI, the corresponding GroupMember resource MUST be deleted.

Schema Representation

GroupMember Core Schema The following is the formal SCIM schema definition for the GroupMember resource. The schemas and meta attributes are common attributes inherited from and are included here for completeness.

membersMetadata Schema Extension This specification defines a schema extension for the SCIM Group resource to support the discoverability of membership management policies. Schema URN: urn:ietf:params:scim:schemas:extension:groupMembers:2.0:Group

The membersMetadata Attribute Definition The extension introduces a single complex attribute to the Group resource: membersMetadata. This attribute is defined as follows. The schemas and meta attributes are common attributes inherited from and are included here for completeness.

Usage When a Service Provider uses this extension, it MUST add the schema URN urn:ietf:params:scim:schemas:extension:groupMembers:2.0:Group to the schemas attribute of the Group resource. The membersMetadata attribute and its sub-attributes are read-only, as they are metadata reported by the Service Provider to the client.

Security Considerations The security considerations for the GroupMember resource are substantially the same as those for the User and Group resources defined in Section 8 of the SCIM Protocol document . All requests MUST be made over a secure channel such as Transport Layer Security (TLS). Authentication and authorization for managing GroupMember resources are the responsibility of the Service Provider. Implementers should consider the following:

A client with permission to read a Group resource's members attribute MUST be granted permission to GET the corresponding GroupMember resources for that group. Access to a Group resource alone does not imply access to its member list — a Service Provider MAY expose group metadata broadly while restricting membership details to privileged clients.
A client authorized to add or remove members from a Group via a PATCH to the Group resource MUST have equivalent POST and DELETE permissions on GroupMember resources for that same group.

IANA Considerations This document requests that IANA register the following URNs in the "SCIM Schemas" registry. URI: urn:ietf:params:scim:schemas:core:2.0:GroupMember Specification: This document Description: Defines the schema for a resource representing a single group membership. URI: urn:ietf:params:scim:schemas:extension:groupMembers:2.0:Group Specification: This document Description: Defines a schema extension for the Group resource that provides metadata about how group memberships are managed.