Cursor-Based Pagination of System of Cross-domain Identity Management (SCIM) Resources
updates
Extracted elements (21)
A service provider MAY require cursor-based pagination to retrieve all results even when the client did not include the cursor parameter, by including a nextCursor in the response to an unpaginated query. This allows service providers to enforce pagination on large result sets regardless of client intent.
Translating from an underlying cursor-based pagination pattern to the index-based pagination defined in RFC 7644 requires the SCIM service provider to fully iterate the underlying cursor, store results, and serve indexed pages from stored results. This pagination translation increases complexity and memory requirements, impeding SCIM adoption for applications where cursor-based pagination is already established.
Implementers adding cursor-based pagination to a service provider that previously supported only index-based pagination should use index as the default pagination method to avoid breaking clients that expect index-based behavior when no pagination parameters are specified.
Service providers implementing cursor pagination that are unable to estimate totalResults MAY choose to omit the totalResults attribute from paged responses, diverging from the RFC 7644 guidance to return an accurate value.
A negative count value SHALL be interpreted as 0. When count is specified, the service provider MUST NOT return more results than requested, though it MAY return fewer.
Clients MUST NOT interpret the lack of published Service Provider Configuration values to mean that no defaults or limits on page sizes or cursor lifetimes exist, or that there is no default pagination method.
previousCursor MUST NOT be returned with the first page of results. Returning previousCursor is OPTIONAL.
Service providers supporting cursor-based pagination MUST include nextCursor in all paged query responses except when returning the last page. nextCursor MUST be omitted from a response only to indicate that there are no more result pages.
The cursor value MUST be empty or omitted for the first request of a cursor-paginated query. Cursor values may only contain characters from the unreserved character set defined in RFC 3986 Section 2.3.
To retrieve another result page, the client MUST query the same service provider endpoint with all query parameters and values identical to the initial query, with the exception of the cursor value, which SHOULD be set to a nextCursor or previousCursor value returned by the service provider.
When a service provider supports both index-based and cursor-based pagination, it MUST choose a default pagination method to use when responding to requests that have not specified a pagination query parameter.
A `pagination` complex attribute is defined for the /ServiceProviderConfig resource with sub-attributes: `cursor` (Boolean, REQUIRED), `index` (Boolean, REQUIRED), `defaultPaginationMethod` (string, OPTIONAL), `defaultPageSize` (positive integer, OPTIONAL), `maxPageSize` (positive integer, OPTIONAL), and `cursorTimeout` (positive integer in seconds, OPTIONAL).
Cursor-based pagination parameters (`cursor`, `count`) may be passed in the body of an HTTP POST to a `/.search` endpoint as defined in RFC 7644 Section 3.4.3, in addition to URL query parameters on GET requests.
Three scimType error detail values are defined for HTTP 400 responses: `invalidCursor` (cursor value is invalid), `expiredCursor` (cursor has expired, client waited too long between requests), and `invalidCount` (count value is out of range or inconsistent with initial query). These extend the error keyword list in RFC 7644 Table 9.
Two response attributes are defined: `nextCursor` (opaque URL-safe string cursor for the next page, MUST be included in all paged responses except the last) and `previousCursor` (optional cursor for reverse traversal, MUST NOT be returned with the first page).
Two URL query parameters are defined for cursor-based pagination: `cursor` (string, the nextCursor value from a previous response, empty or omitted for the first request, restricted to RFC 3986 unreserved characters) and `count` (desired maximum results per page; negative values treated as 0).
IANA has updated the 'SCIM Schema URIs for Data Resources' registry (established by RFC 7643) to add RFC 9865 Section 2 as a reference for urn:ietf:params:scim:api:messages:2.0:ListResponse and urn:ietf:params:scim:api:messages:2.0:SearchRequest, and the 'SCIM Server-Related Schema URIs' registry to add Section 4 as a reference for urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig.
Cursor values should be obfuscated to prevent clients from interpreting or forging cursors. Service providers should be able to detect forged cursor values and return an invalidCursor error. Error responses for out-of-scope or non-existent pages must use identical messages to avoid leaking information about underlying data or authorization failures.
Implementers MUST ensure that pagination through result sets is strictly confined to data that the actor's current identity has been authorized to access, even if the actor obtained a cursor generated by a different actor. Authorization checks MUST be continuously applied as an actor navigates through a result set; cursor possession MUST NOT grant supplementary access privileges.
Retaining substantial data or metadata per cursor creates a Denial-of-Service vector: numerous initial queries allocating cursors can exhaust service-provider resources. Mitigations include requiring authentication for large result sets, rate limiting per RFC 6585, administrator-configurable cursor count ceilings, and resource-efficient cursor invalidation mechanisms.
Service providers SHOULD invalidate all cursors corresponding to an actor immediately following a permission change, to prevent post-permission-change queries using old cursors from succeeding. Alternatively, providers may retain cursors but must update result set metadata to reflect new permissions.