SCIM Group Membership 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 memberships 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. These failure points have already led to workarounds that avoid the problem rather than solve it. Some service providers do not return the "members" attribute at all, instead exposing membership only through indirect filter queries against the Group resource. Some clients request that the "members" attribute be excluded from Group responses altogether, using the excludedAttributes query parameter defined in , for the same reason; this leaves those clients able to push membership additions and removals but unable to read back and reconcile the service provider's actual membership state. This document proposes the "GroupMembership" 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 scalable 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 GroupMembership Resource This section defines the GroupMembership 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 GroupMembership resource represents a direct membership only. Indirect memberships, as defined in Section 4.1.2, MUST NOT be represented as GroupMembership resources. A service provider MUST NOT maintain more than one GroupMembership resource with the same group.value and member.value.

Resource Properties The GroupMembership 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 GroupMembership resource's core schema is urn:ietf:params:scim:schemas:core:2.0:GroupMembership. This is a REQUIRED attribute. This attribute is a common attribute inherited from .

id: A unique identifier for the GroupMembership 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 /GroupMemberships/{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. When populated, this value MUST match the current displayName of the referenced Group resource.

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. The value MUST be the name of the member's ResourceType, as defined in Section 6, 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. When populated, this value MUST match the current displayName of the referenced resource.

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

Service providers MAY optimize payload size by omitting the group.display and member.display sub-attributes entirely, or by configuring them as returned: "request" (available only when explicitly requested via the attributes query parameter). Because these sub-attributes are optional and read-only, a service provider that never implements them is fully conformant. If a service provider supports neither creating nor deleting GroupMembership resources, all attributes in the schema definition returned from /Schemas MUST have their mutability property set to readOnly. A service provider that does not support POST or DELETE requests for GroupMembership resources MUST respond to them with 501 Not Implemented, as defined in Section 3.12. A service provider that supports these operations but does not permit them for the requesting client responds with 403 Forbidden. The ResourceType and Schema resources that describe GroupMembership are discoverable via the /ResourceTypes and /Schemas endpoints, respectively, per . Examples are provided in the Resource Type Representation and GroupMembership Core Schema sections.

JSON Representation The following is an example of a GroupMembership resource in JSON format. This example represents the membership of a user in a group:

Resource Type Representation The service provider's /ResourceTypes endpoint MUST include a ResourceType resource for "GroupMembership". Example ResourceType entry:

groupMemberships Group Schema Extension This specification defines a schema extension for the Group resource with a single attribute, membersEmbedded, which states whether a group's full current membership is delivered in its members attribute. The extension lets a service provider add support for GroupMembership without changing how it returns members, so existing clients are unaffected, while clients that understand the extension get a per-group signal. A service provider that only exposes memberships through GroupMembership MAY omit Group.members and need not use this extension. The schema URN for the extension is urn:ietf:params:scim:schemas:extension:groupMemberships:2.0:Group. A service provider that includes this extension on a Group MUST support the GroupMembership resource. A service provider that supports this extension SHOULD list its schema URN in the schemaExtensions attribute of its Group ResourceType, with required set to false. As with any schema extension, a Group that includes the extension lists its URN in the schemas attribute, per Section 3.

The membersEmbedded Attribute

membersEmbedded: A boolean that states whether the group's full current membership is present in the members attribute. A value of true is a guarantee by the service provider that the group's full current membership is present in the members attribute, so an omitted or empty members attribute means the group has no members. This guarantee applies only to responses in which the members attribute would be returned given the request's attributes and excludedAttributes parameters ( Section 3.4.2.5). A client that excludes members from a response cannot conclude from a value of true that the group has no members. A value of false indicates that the service provider does not guarantee that members contains the full membership. The members attribute may in fact be full, partial, omitted, or empty; for example, a service provider that cannot return accurate membership above a certain size can always report false, even for a group whose members happens to be complete. When the value is false, a client that needs the group's complete membership SHOULD retrieve it from /GroupMemberships, filtered on the group's id. If the attribute is absent, the service provider makes no statement, and members is interpreted as defined in . This attribute does not affect which operations are supported on members or on GroupMembership resources, and does not indicate which is the preferred way to manage memberships.

A client retrieves a group's memberships from /GroupMemberships using a filter on the group's id, for example /GroupMemberships?filter=group.value eq "[Group_ID]".

Example Group Resources

Example of a Group with membersEmbedded Set to false The following is a Group with a large number of members. membersEmbedded is false and the members attribute is omitted; the client queries /GroupMemberships for this group's membership. Example Request: GET /scim/v2/Groups/e9e30dba-f08f-4139-944c-2e6949b80b05

Example of a Group with membersEmbedded Set to true The following is a Group with a small number of members. membersEmbedded is true, so the members attribute holds the group's full membership. Example Request: GET /scim/v2/Groups/a0b1c2d3-f08f-4139-944c-2e6949b80b05

Managing GroupMembership Resources This section describes how GroupMembership resources are managed using the SCIM protocol. A GroupMembership is fundamentally a link between a group and a member, not a resource with independently editable state. The group and member attributes of the core schema are declared immutable, so a different group or member value represents a different membership, not an edit to the existing one; as a result, PATCH and PUT have nothing in the core schema to act on. This does not prohibit a service provider from supporting PATCH or PUT as methods; a service provider that adds its own mutable extension attributes to this resource MAY support PATCH for those attributes without contradicting this document. If a service provider supports the GroupMembership resource, it MUST make available via /GroupMemberships every membership the requesting client is authorized to view. This requirement is independent of whether Group.members is also supported or returned; a service provider MAY choose not to return Group.members for groups whose membership is exposed via GroupMembership, and this requirement does not mandate supporting Group.members at all. Service providers MAY also support management of group memberships through the existing members attribute of the Group resource as defined in for the purpose of backwards compatibility with existing clients. When doing so, the service provider MUST maintain consistency between the state of the members attribute and the state of the corresponding GroupMembership resources. For example, if a DELETE request to a /GroupMemberships/{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 GroupMembership resource MUST be deleted. When a Group resource is deleted, the service provider MUST delete every GroupMembership resource whose group.value references that group. When a member resource is deleted, the service provider MUST delete every GroupMembership resource whose member.value references that resource. Deleted GroupMembership resources are subject to the requirements of Section 3.6. When a GroupMembership resource is created or deleted and the service provider supports the members attribute of the parent Group, the service provider MUST update the parent Group resource's meta.lastModified and, if it supports resource versioning ( Section 3.14), its meta.version. A change to a Group or member resource that does not create or delete a given GroupMembership resource does not modify that GroupMembership resource, and MUST NOT change its meta.lastModified or meta.version. This includes changes to the referenced resource's displayName, even when reflected in the derived group.display or member.display sub-attributes, and the addition or removal of other members of the same group. The display sub-attributes are values derived from the referenced resources, not state of the GroupMembership resource itself.

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

Request: POST /scim/v2/GroupMemberships
Response: 201 Created with the full GroupMembership 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 GroupMembership resource. The service provider MUST return a 400 Bad Request error with a scimType of invalidValue if any of the following is true:

The referenced group or member does not exist.
The referenced member is of a resource type that the service provider does not allow as a member of the referenced group, for example a Group when the service provider does not support nested groups.
The service provider does not permit circular group nesting, and creating the membership would make a group a direct or indirect member of itself.

If a GroupMembership resource with the same group.value and member.value already exists, the service provider MUST return a 409 Conflict error with a scimType of uniqueness, as defined in Section 3.3. The service provider MUST NOT create a second GroupMembership resource or return a successful response. Example Request: POST /scim/v2/GroupMemberships

Retrieving GroupMembership Resources (GET) GroupMembership resources can be retrieved by sending a GET request to the GroupMemberships endpoint. Clients can retrieve an individual resource by its id, or retrieve a collection of resources that can be narrowed using a filter on attributes such as group.value or member.value.

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

Pagination Service providers MUST support pagination of GroupMembership resources using at least one of index-based pagination, as defined in Section 3.4.2.4, or cursor-based pagination, as defined in . Service providers SHOULD support cursor-based pagination for GroupMembership resources, because index-based pagination can return inconsistent results when memberships change while a client is paging through them ( Section 3.4.2.4). Service providers MUST indicate which pagination methods they support using the pagination attribute of /ServiceProviderConfig, as defined in Section 4. Index-based Pagination: The startIndex and count query parameters, as defined in .

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

Cursor-based Pagination: The cursor and count query parameters, as defined in . The first request includes an empty cursor parameter, and each subsequent request sets cursor to the nextCursor value from the previous response.

Example (first page): GET /scim/v2/GroupMemberships?count=1000&cursor
Example (next page): GET /scim/v2/GroupMemberships?count=1000&cursor=aW5kZXg9MTAx

The response for a paginated request is a ListResponse containing the GroupMembership resources for the current page. The following is an example of a cursor-paginated response: A GET request to /GroupMemberships without a filter returns all memberships across all groups. Service providers SHOULD impose a reasonable per-page limit on such unconstrained listings (e.g., a maximum of 1000 results per page) to avoid unbounded computation over the full membership dataset. A service provider MAY reject a request without a filter with a 400 Bad Request error and a scimType of tooMany, as defined in Section 3.12. Memberships remain available to clients in that case through requests filtered on group.value or member.value. Service providers MUST return GroupMembership resources in a stable order across the pages of a single query, so that a client paging through the results receives each matching membership exactly once, provided the underlying memberships do not change during the query. For example, a service provider can meet these requirements without materializing the entire membership dataset in memory by ordering results internally by group.value, so that pagination can stream across group boundaries.

Filtering Service providers MUST support filtering on the group.value and member.value attributes using the eq operator. 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." Service providers MUST also support combining these two filters with the and operator, so that a client can determine whether a specific membership exists and obtain its id.

To find all members of a group:: GET /scim/v2/GroupMemberships?filter=group.value eq "e9e30db"

To find all groups for a member:: GET /scim/v2/GroupMemberships?filter=member.value eq "2819c22"

To find a specific membership:: GET /scim/v2/GroupMemberships?filter=group.value eq "e9e30db" and member.value eq "2819c22"

If a service provider supports more than one resource type as a group member, it MUST also support filtering on member.type using the eq operator, alone or combined with the filters above using and, so that clients can narrow queries to a specific member resource type without enumerating and filtering results client-side.

To find all User members of a group:: GET /scim/v2/GroupMemberships?filter=group.value eq "e9e30db" and member.type eq "User"

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

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

A client that does not know the id of the GroupMembership resource it wants to delete can obtain it with a query filtered on both group.value and member.value (see Filtering). Clients that create memberships with POST can avoid this lookup by retaining the id returned in the 201 Created response. If the service provider supports modifying the members attribute of the Group resource, a client can instead remove the member with a PATCH request to the Group, using a remove operation whose path is members[value eq "[Member_ID]"], as shown in Section 3.5.2.2. This removes the membership without requiring the client to know the id of the GroupMembership resource.

Bulk Operations Clients can create and delete multiple GroupMembership 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:

Schema Representation

GroupMembership Core Schema The following is the formal SCIM schema definition for the GroupMembership resource. The schemas and meta attributes are common attributes inherited from and are included here for completeness. The referenceTypes values of member.$ref in the schema definition above are non-normative examples. A service provider MAY add or remove resource types to reflect the resource types it supports as members of a group. The value sub-attributes of group and member are defined with caseExact set to true because they contain resource id values, which Section 3.1 defines as case-exact. This intentionally differs from the value sub-attribute of the members attribute in the Group schema defined in , which is defined with caseExact set to false.

groupMemberships Schema Extension This section contains the schema definition for the groupMemberships schema extension, described in the groupMemberships Group Schema Extension section. Schema URN: urn:ietf:params:scim:schemas:extension:groupMemberships:2.0:Group

The membersEmbedded Attribute Definition The extension introduces a single boolean attribute to the Group resource, membersEmbedded, defined below. The schemas and meta attributes are common attributes inherited from and are included here for completeness.

Security Considerations The security considerations for the GroupMembership resource are substantially the same as those for the User and Group resources defined in Section 7 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 GroupMembership resources are the responsibility of the service provider. Implementers should consider the following:

A service provider MUST apply authorization to GET requests for GroupMembership resources, including requests filtered on group.value or member.value, that is equivalent to the authorization it applies to reading the members attribute of the corresponding Group resources. Access to a Group resource alone does not imply access to its member list, and access to a member resource (such as a User) alone does not imply access to that resource's group memberships; a service provider MAY expose group or member metadata broadly while restricting membership details to privileged clients. The membership relationship can be more sensitive than either the member or the group individually, regardless of the member's resource type.
A service provider MUST NOT reveal, through error responses or through the totalResults value of a query response, the existence of Group resources, member resources, or GroupMembership resources that the requesting client is not authorized to read. A client authorized to add members to a group can learn from a 409 Conflict response whether a member already belongs to that group; this is inherent in the operation and does not violate this requirement. When a client is not authorized to read a group or member referenced in a POST request, the service provider SHOULD return the same response it would return if the referenced resource did not exist.
A service provider MUST apply authorization to POST and DELETE requests for a group's GroupMembership resources that is equivalent to the authorization it applies to adding or removing members of that Group through PATCH.
Queries against /GroupMemberships without a filter or with a broad filter, and the work needed to populate the group.display and member.display sub-attributes, can be expensive at the scale this document targets, and can be used to degrade a service provider's availability. Service providers can mitigate this using per-page limits and the tooMany error defined in Section 3.12.

Schema Registration Templates The following registration templates, as defined in Section 10.3.2 of , describe the schema URIs registered by this document.

GroupMembership Core Schema Registration

Schema URI:: urn:ietf:params:scim:schemas:core:2.0:GroupMembership

Schema Name:: Group Membership

Intended or Associated Resource Type:: GroupMembership

Purpose:: Represents a single membership of a member (a User, a Group, or another resource type) in a Group as a top-level resource, so that memberships can be paginated, filtered, created, and deleted individually.

Single-value Attributes:: id (string); group (complex: value, $ref, display); member (complex: value, $ref, type, display); meta (complex).

Multi-valued Attributes:: None, other than the common schemas attribute.

groupMemberships Group Extension Registration

Schema URI:: urn:ietf:params:scim:schemas:extension:groupMemberships:2.0:Group

Schema Name:: Group Memberships Extension

Intended or Associated Resource Type:: Group

Purpose:: Indicates whether all of a group's memberships are embedded in its members attribute.

Single-value Attributes:: membersEmbedded (boolean).

Multi-valued Attributes:: None.

IANA Considerations This document requests that IANA register the following schema URIs in the "SCIM Schema URIs for Data Resources" registry, within the "System for Cross-domain Identity Management (SCIM) Schema URIs" registry group established by . The registration templates for both are provided in the Schema Registration Templates section.

Schema URI:: urn:ietf:params:scim:schemas:core:2.0:GroupMembership

Name:: Group Membership

Reference:: This document

Schema URI:: urn:ietf:params:scim:schemas:extension:groupMemberships:2.0:Group

Name:: Group Memberships Extension

Reference:: This document

Acknowledgments The author would like to thank Matthias Winter, Hans-Joerg Happel, and Paul Lanzi for their detailed reviews and suggestions on the SCIM mailing list and in the draft's repository.