| RFC 9865 | SCIM Cursor Pagination | October 2025 |
| Peterson, et al. | Standards Track | [Page] |
This document updates RFCs 7643 and 7644 by defining additional System for Cross-Domain Identity Management (SCIM) query parameters and result attributes to allow use of cursor-based pagination in SCIMservice providers that are implemented with existing codebases, databases, or APIs where cursor-based pagination is already well established.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9865.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The two common patterns for result pagination are index-based paginationand cursor-based pagination. Rather thanattempt to compare and contrast the advantages and disadvantages ofcompeting pagination patterns, this document simply recognizes thatSystem for Cross-Domain Identity Management (SCIM) service providers are commonly implemented as aninteroperability layer on top of already existing applicationcodebases, databases, and/or APIs that already have a well established pagination pattern.¶
Translating from an underlying cursor-based pagination pattern to theindex-based pagination defined inSection 3.4.2.4 of [RFC7644]ultimately requires the SCIM service provider to fully iterate theunderlying cursor, store the results, and then serve indexed pagesfrom the stored results. This task of "pagination translation"increases complexity and memory requirements forimplementing a SCIM service provider, and may be an impediment toSCIM adoption for some applications and identity systems.¶
This document defines a simple addition to the SCIM protocol thatallows SCIM service providers to reuse underlying cursors withoutexpensive translation. Support for cursor-based pagination in SCIMencourages broader cross-application identity managementinteroperability by encouraging SCIM service provider implementationsfor applications and identity systems where cursor-based paginationis already well established.¶
This document updates RFCs 7643 and 7644 because it adds attributes toexisting structures from those documents, as described inSection 2. These changes are invoked when using the "cursor" parameter when making SCIM search requests using GET or POST methods.¶
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[RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document uses the terms defined inSection 1.2 of [RFC7643].¶
The following table describes the URL pagination query parameters for requesting cursor-based pagination:¶
| Parameter | Description |
|---|---|
cursor | The string value of the nextCursor attribute from a previous result page. The cursor valueMUST be empty or omitted for the first request of a cursor-paginated query. This value may only contain characters from the unreserved character set defined inSection 2.3 of [RFC3986]. |
count | Specifies the desired maximum number of query results per page, e.g., 10. A negative valueSHALL be interpreted as "0". A value of "0" indicates that no resource results are to be returned except for "totalResults". When specified, the service providerMUST NOT return more, although itMAY return fewer, results. If unspecified, the maximum number returned is set by the service provider. |
The following table describes cursor-based pagination attributes returned in a paged query response:¶
| Element | Description |
|---|---|
nextCursor | A cursor value string thatMAY be used in a subsequent request to obtain the next page of results. Service providers supporting cursor-based paginationMUST includenextCursor in all paged query responses except when returning the last page.nextCursorMUST be omitted from a response only to indicate that there are no more result pages. |
previousCursor | A cursor value string thatMAY be used in a subsequent request to obtain the previous page of results. ReturningpreviousCursor isOPTIONAL.previousCursorMUST NOT be returned with the first page. |
Cursor values are URL-safe strings that are opaque to the client.To retrieve another result page for a query, the clientMUST query the same serviceprovider endpoint with all query parameters and values beingidentical to the initial query with the exception of thecursor value,whichSHOULD be set to anextCursor (orpreviousCursor) value thatwas returned by the service provider in a previous response.¶
For example, to retrieve the first 10 users withuserName startingwithJ, use an empty cursor and set the count to 10:¶
GET /Users?filter=userName%20sw%20J&cursor&count=10Host: example.comAccept: application/scim+jsonAuthorization: Bearer U8YJcYYRMjbGeepD¶
The SCIM service provider in response to the query above returns metadata regarding pagination similarto the following example (Resources omitted for brevity):¶
HTTP/1.1 200 OKContent-Type: application/scim+json{ "totalResults":100, "itemsPerPage":10, "nextCursor":"VZUTiyhEQJ94IR", "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "Resources":[{ ... }]}¶Given the example above, to request the next page of results, use thesame query parameters and values except set the cursor to the valueofnextCursor (VZUTiyhEQJ94IR):¶
GET /Users?filter=username%20sw%20J&cursor=VZUTiyhEQJ94IR&count=10Host: example.comAccept: application/scim+jsonAuthorization: Bearer U8YJcYYRMjbGeepD¶
The service provider responds with:¶
HTTP/1.1 200 OKContent-Type: application/scim+json{ "totalResults": 100, "itemsPerPage": 10, "previousCursor: "ze7L30kMiiLX6x", "nextCursor": "YkU3OF86Pz0rGv", "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "Resources":[{ ... }]}¶In the example above, the response includes the optionalpreviousCursor indicating that the service provider supports forwardand reverse traversal of result pages.¶
As described inSection 3.4.1 of [RFC7644], service providers shouldreturn an accurate value for totalResults, which is the total numberof resources for all pages. Service providers implementing cursorpagination that are unable to estimate totalResultsMAY choose to omit the totalResults attribute.¶
If a service provider encounters invalid pagination queryparameters (invalid cursor value, count value, etc) or other errorconditions, the service providerSHOULD return the appropriate HTTPresponse status code and detailed JSON error response as defined inSection 3.12 of [RFC7644].¶
For HTTP status code 400 (Bad Request) responses, the following detail error types are defined. These error types extend the list defined in Table 9 ("SCIM Detail Error Keyword Values") ofSection 3.12 of [RFC7644]¶
| scimType | Description | Applicability |
|---|---|---|
invalidCursor | Cursor value is invalid. Cursor valueSHOULD be empty to request the first page and set to thenextCursor orpreviousCursor value for subsequent queries. | GET (Section 3.4.2 of [RFC7644]) |
expiredCursor | Cursor has expired. Do not wait longer than service provider'scursorTimeout to request additional pages. | GET (Section 3.4.2 of [RFC7644]) |
invalidCount | Count value is invalid. Count value must be between 0 and service provider's maxPageSize and must be equal to the count value of the initial query. | GET (Section 3.4.2 of [RFC7644]) |
If sorting is implemented as describedSection 3.4.2.3 of [RFC7644],then cursor-paged results should be sorted.¶
A service providerMAY require cursor-based pagination toretrieve all results for a query by including anextCursor value inthe response, even when the query does not include thecursorparameter.¶
For example:¶
GET /UsersHost: example.comAccept: application/scim+json¶
The service provider may respond to the above query with a pagecontaining defaultPageSize results and anextCursor value as shownin the below example (Resources omitted for brevity):¶
HTTP/1.1 200 OKContent-Type: application/scim+json{ "totalResults": 5000, "itemsPerPage": 100, "nextCursor": "HPq72Pax3JUaNa", "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "Resources": [{ ... }]}¶When a service provider supports both index-based and cursor-based pagination, clients can use the 'startIndex' or 'cursor' query parameters to request a specific method. Additionally, service providers supporting both pagination methodsMUST choose a default pagination method to use when responding to requests that have not specified a pagination query parameter.¶
Implementers of SCIM service providers that previously supported only index-based pagination and are adding support for cursor-based pagination should use index as the default pagination method to avoid incompatibility with clients that expect index-based pagination behaviors when no pagination query parameters are specified.¶
SCIM clients can query theService Provider Configuration (Section 4) endpoint to determine if index-based, cursor-based, or both types of pagination are supported and which of these is the default.¶
Section 3.4.3 of [RFC7644] defines how clients may execute queries without passing parameters on the URL by using thePOST verb combined with the/.search path extension execute. When posting to/.search, the client would pass the parameters defined inSection 2 in the body of the POST request. For example:¶
POST /User/.searchHost: example.comAccept: application/scim+jsonAuthorization: Bearer U8YJcYYRMjbGeepD{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:SearchRequest"], "attributes": ["displayName", "userName"], "filter": "displayName sw \"smith\"", "cursor": "", "count": 10}¶Which would return a result containing anextCursor value that maybe used by the client in a subsequent call to return the next page ofresources:¶
HTTP/1.1 200 OKContent-Type: application/scim+json{ "totalResults": 100, "itemsPerPage": 10, "nextCursor": "VZUTiyhEQJ94IR", "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "Resources": [{ ... }]}¶The/ServiceProviderConfig resource defined inSection 4 of [RFC7644]facilitates discovery of SCIM service provider features. A SCIMservice provider implementing cursor-based paginationSHOULD includethe following additional attribute in a JSON document returned by the/ServiceProviderConfig endpoint:¶
The following sub-attributes are defined:¶
A Boolean value specifying support of cursor-based pagination.REQUIRED.¶
A Boolean value specifying support of index-based pagination.REQUIRED.¶
A string value specifying the type of pagination that the service provider defaults to when the client has not specified which method it wishes to use. Possible values are "cursor" and "index".OPTIONAL.¶
Positive integer value specifying the default number of results returned in a page when a count is not specified in the query.OPTIONAL.¶
Positive integer specifying the maximum number of results returned in a page regardless of what is specified for the count in a query. The maximum number of results returned may be further restricted by other criteria.OPTIONAL.¶
Positive integer specifying the minimum number of seconds that a cursor is valid between page requests. Clients waiting too long between cursor pagination requests may receive an invalid cursor error response. No value being specified may mean that there is no cursor timeout or that the cursor timeout is not a static duration.OPTIONAL.¶
Service providers may choose not to advertise Service Provider Configuration information regarding default pagination method, page size, or cursor validity. ClientsMUST 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. Service providers may choose not to publish values for the pagination sub-attributes for many reasons. Examples include:¶
Service providers containing multiple resource types may have different values set for each resource type.¶
Default and maximum page size may be determined by factors besides or in addition to the number of resources returned, such as the size of each resource on the page.¶
Before using cursor-based pagination, a SCIM clientMAY fetch theService Provider Configuration document from the SCIM serviceprovider and verify that cursor-based pagination is supported.¶
For example:¶
GET /ServiceProviderConfigHost: example.comAccept: application/scim+json¶
A service provider supporting both cursor-based pagination and index-based pagination would return a document similar to the following(fullServiceProviderConfig schema defined inSection 5 of [RFC7643]has been omitted for brevity):¶
HTTP/1.1 200 OKContent-Type: application/scim+json{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"], ... "pagination": { "cursor": true, "index": true, "defaultPaginationMethod": "cursor", "defaultPageSize": 100, "maxPageSize": 250, "cursorTimeout": 3600 }, ...}¶This section elaborates on the security considerations associated with the implementation of cursor pagination in SCIM. This document is under the same security and privacy considerations of those described in[RFC7644]. It is imperative that implementers additionally consider the following security aspects to safeguard against both deliberate attacks and inadvertent misuse that may compromise the system's security posture.¶
The threat landscape is characterized by two primary types of actors:¶
Unauthenticated and Authenticated Malicious Actors: These individuals or entities represent a malevolent threat. Their objectives include unauthorized access to data, alteration, or deletion through cursor-enabled queries. They may also seek to deplete service provider resources deliberately, aiming to cause a denial-of-service state, thereby reducing service availability.¶
Authenticated Benign Users: This category includes legitimate users who, due to confusion or a lack of understanding, inadvertently engage in actions that consume service-provider resources excessively. Such actions, while not ill intended, can lead to unintended denial of service by overwhelming the service provider's capacity.¶
To ensure that confidential data remains appropriately secured:¶
ImplementersMUST ensure that pagination through results sets is strictly confined to the data that the actor's current identity has been authorized to access. This holds true even in cases where the actor has obtained a cursor pertaining to a result set that was generated by a different actor.¶
Authorization checksMUST be continuously applied as an actor navigates through the result set associated with a cursor. Under no circumstances should possession of a cursor be interpreted as granting any supplementary access privileges to the actor.¶
When possible, service providersSHOULD invalidate all cursors corresponding to an actor immediately following a change in permissions. This ensures that any queries executed post-permission change, utilizing old cursors, will be denied. As an alternative approach, service providers may opt to retain the existing cursors but must ensure that any metadata tied to the result set, such as record counts, is updated to reflect the new permissions accurately.¶
In alignment withSection 2, cursor values are URL-safe strings that are opaque to clients. Service providers should obfuscate cursorsvalues to prevent clients from interpreting cursors or forging new cursors. Service providers should be able to easily detect forged cursor values and immediately return aninvalidCursor as described inSection 2.1.¶
The service providerMUST handle error scenarios without exposing sensitive data. For instance, if an actor attempts to access a page of results outside their authorized scope, or if a request is made for a non-existent page, the service provider should respond with identical error messages, so as not to disclose any details of the underlying data or the nature of the authorization failure. It is acceptable, however, for the service provider to log different messages to a log accessible by administrators or other authorized personnel.¶
The concern for availability primarily stems from the potential for Denial-of-Service (DoS) attacks. If the service provider elects to retain substantial data or metadata for each cursor, numerous initial queries that allocate cursors could strain and eventually exhaust service-provider resources. Such an attack could be orchestrated by an attacker with malicious intent or could occur unintentionally as a result of client testing or bugs.¶
To mitigate risks, the following strategies are recommended for service providers:¶
Clients should authenticate to retrieve large result sets. Anonymous queries yielding numerous results may return an HTTP status code 400 (Bad Request) with the error type "tooMany," as outlined inSection 3.12 of [RFC7644].¶
Implement rate limiting to control the volume and cadence of cursor requests. This approach should adhere to established standards for rate limiting; details can be found in[RFC6585].¶
Allow administrator of the service provider to set a ceiling on the number of cursors permissible at any given time or to specify a maxPageSize value. Guidance on configuring such values should be documented in the implementation administrator/installation guide.¶
Cursor invalidation mechanisms (including mechanisms triggered by permissions changes) must be designed to be resource-efficient to prevent them from being exploited for DoS attacks.¶
Using URIs to describe and locate resources has its own set of security considerations, as discussed inSection 7 of [RFC3986]. Implementations should also refer to[BCP195] and[RFC9110] for additional security considerations that are relevant for underlying TLS and HTTP protocols.¶
IANA has amended the "System for Cross-domain Identity Management (SCIM) Schema URIs" registry group established by[RFC7643] as described below.¶
IANA has updated the "SCIM Schema URIs for Data Resources" registry as follows:¶
For theurn:ietf:params:scim:api:messages:2.0:ListResponse,Section 2 of this document has been added to the References column.¶
For theurn:ietf:params:scim:api:messages:2.0:SearchRequest,Section 2 of this document has been added to the References column.¶
IANA has updated the "SCIM Server-Related Schema URIs" registry as follows:¶
The authors would also like to acknowledge the following individuals who provided valuable feedback while reviewing the document:Aaron Parecki,David Brossard,Dean H. Saxe, andPamela Dingle.¶
The authors would like to acknowledge the contribution ofPaul Lanzi (IDenovate) in leading the writing of the Security Considerations section.¶