SCIM 2.0 Group Member Resource

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.

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.

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.

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.

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.

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.

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 3, 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. Service Providers that support both mechanisms SHOULD clearly document their consistency model. It is RECOMMENDED that for groups with a very large number of members, Service Providers implement the members attribute as write-only by setting the 'returned' schema property to 'never'.

Schema Representation

GroupMember Core Schema The following is the formal SCIM schema definition for the GroupMember resource.

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:

Usage When a Service Provider uses this extension, it MUST add the schema URN urn:ietf:params:scim:schemas:extension:group:2.0:membersMetadata 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. Example schemas attribute in a Group resource:

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: Access controls for GroupMember resources may be inherited from the parent Group. For example, a client that has permission to view a Group and its members should also have permission to GET the corresponding GroupMember resources. A client authorized to add or remove members from a Group (e.g., via a PATCH to the Group resource) should have equivalent permissions to POST and DELETE GroupMember resources for that same group. When a client attempts to retrieve one or more GroupMember resources, whether through a direct GET to a resource URI (/GroupMembers/{id}) or through a list request to the endpoint (/GroupMembers), the Service Provider's authorization decision MUST be based on the client's permission to read the parent Group. A client that has permission to read a Group resource MUST also be granted permission to retrieve any GroupMember resource where the group.value attribute matches the id of that Group. This policy mirrors the existing SCIM behavior where access to a Group resource implies access to its member list. A Service Provider MUST NOT require an additional authorization check on the member resource itself as a condition for retrieving a GroupMember resource.

IANA Considerations This document requests that IANA register a new URN 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.