AWS singlesignon documentation change
Summary
Updated ListGroups API documentation with pagination support, increased maximum results per page from 50 to 100, added query parameters (cursor/count/filter), and expanded filter examples including members.value filtering
Security assessment
The changes focus on API functionality improvements (pagination, filtering) rather than addressing security vulnerabilities. While the documentation now shows bearer token usage in examples, this is standard authentication documentation rather than new security guidance. The ValidationException update regarding filter parameter changes during pagination appears to prevent inconsistent query results rather than mitigate a security risk.
Diff
diff --git a/singlesignon/latest/developerguide/listgroups.md b/singlesignon/latest/developerguide/listgroups.md index 7414ea2ec..9f61a1be3 100644 --- a//singlesignon/latest/developerguide/listgroups.md +++ b//singlesignon/latest/developerguide/listgroups.md @@ -5 +5 @@ -Not supportedConstraintsErrorsExamplesFilter examples +Not supportedQuery ParametersConstraintsErrorsPagination ExamplesExamplesFilter examples @@ -9 +9 @@ Not supportedConstraintsErrorsExamplesFilter examples -You can use the `/Groups` endpoint to filter queries on a list of existing groups by making a `GET` request with additional filter information. Only a maximum of 50 results can be returned. See the **Constraints** section for a list of available filters. +You can use the `/Groups` endpoint to filter queries on a list of existing groups by making a `GET` request with additional filter information. A maximum of 100 results can be returned per page. See the **Constraints** section for a list of available filters. @@ -19,0 +20,21 @@ The IAM Identity Center SCIM implementation does not support the following aspec +## Query Parameters + +ListGroups currently supports the following optional query parameters: + + * `cursor` used to specify which page to retrieve in paginated API calls. + + * Pattern: [-a-zA-Z0-9+=/:_]* + + * Response format: Including the cursor parameter changes the default response format from non-paginated (with totalResults, startIndex, and itemsPerPage fields) to cursor-based paginated results (with itemsPerPage and nextCursor fields) + + * `count` used to specify the maximum number of results per page + + * Valid Range: Minimum value of 1. Maximum value of 100. + + * Default: 100 + + * `filter` used to filter out specific groups + + + + @@ -24 +45,7 @@ The IAM Identity Center SCIM implementation has the following constraints for th - * At this time, the `ListGroups` API is only capable of returning up to 50 results. + * The `ListGroups` API is capable of returning up to a maximum of 100 results per page. + + * Supported filter combinations: (`displayName`), (`externalId`), (`members.value`), (`id` and `member`), and (`member` and `id`). Note that the use of id as an individual filter, while valid, should be avoided as there is already a getGroup endpoint available. + + * Pagination requests must include `cursor` in the query parameters + + * The first request made with cursor must be empty (eg. https://.../Groups?cursor) @@ -26 +53,3 @@ The IAM Identity Center SCIM implementation has the following constraints for th - * Supported filter combinations: (`displayName`), (`externalId`), (`id` and `member`), and (`member` and `id`). Note that the use of id as an individual filter, while valid, should be avoided as there is already a getGroup endpoint available. + * If the response includes a nextCursor field, its value can be used as the cursor value to retrieve the next page of results + + * Paginated calls may return less results than count but as long as nextCursor is present in the response, additional pages are available. @@ -41 +70 @@ Error | Condition | HTTP Status Code -`ValidationException` | Request cannot be parsed, is syntactically incorrect, or violates schema. This error also occurs if the operation is unsupported. | 400 +`ValidationException` | Request cannot be parsed, is syntactically incorrect, or violates schema. This error also occurs if the operation is unsupported, or if filter parameters are changed between pagination requests. | 400 @@ -47,0 +77,47 @@ Error | Condition | HTTP Status Code +## Pagination Examples + +### Example Request For Getting the First Page + +###### Example Request + + + GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?cursor + Authorization: Bearer <bearer_token> + +###### Example Response + + + { + "itemsPerPage": 100, + "nextCursor": "VGVzdEdyb3VwQ3Vyc29y", + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "Resources": [ + ... + ] + } + +### Example Request For Getting the Next Page + +_Note: the example does not include a`nextCursor` field since the current page is the last page of results_ + +###### Example Request + + + GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?cursor=VGVzdEdyb3VwQ3Vyc29y + Authorization: Bearer <bearer_token> + +###### Example Response + + + { + "itemsPerPage": 100, + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "Resources": [ + ... + ] + } + @@ -164,0 +241,2 @@ For the ListGroup endpoint we support three different combinations of filters as + * `members.value` + @@ -266,0 +345,82 @@ See the following examples. + } + +### members.value + +#### Example Request Without Pagination + +###### Example Request + + + GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?filter=members.value eq "04285428-40b1-7000-1624-dbde7efebbbf" + Authorization: Bearer <bearer_token> + +###### Example Response + + + { + "totalResults": 100, + "itemsPerPage": 100, + "startIndex": 1, + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "Resources": [ + { + "id": "d468e4d8-c051-703d-dd84-28caf445f15e", + "externalId": "eid_RuvdCnwuJD4KNi2zyiRe", + "meta": { + "resourceType": "Group", + "created": "2025-08-08T17:28:12Z", + "lastModified": "2025-08-08T17:28:12Z" + }, + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:Group" + ], + "displayName": "display_name_eid_RuvdCnwuJD4KNi2zyiRe", + "members": [] + }, + ... + ] + } + +#### Example Request With Pagination + +###### Example Request + + + GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?cursor&filter=members.value eq "04285428-40b1-7000-1624-dbde7efebbbf" + Authorization: Bearer <bearer_token> + +###### Example Response + + + { + "itemsPerPage": 100, + "nextCursor": "Q3Vyc29yR3JvdXBzRmlsdGVy", + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "Resources": [ + ... + ] + } + +#### Example Request For Getting the Next Page + +###### Example Request + + + GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?cursor=Q3Vyc29yR3JvdXBzRmlsdGVy&filter=members.value eq "04285428-40b1-7000-1624-dbde7efebbbf" + Authorization: Bearer <bearer_token> + +###### Example Response + + + { + "itemsPerPage": 10, + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "Resources": [ + ... + ]