ListGroups
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.
Not supported
The IAM Identity Center SCIM implementation does not support the following aspects of this API operation.
-
GetGroup
andListGroups
return an empty member list. To see group info for a certain member, callListGroups
with a member filter. (See the examples that follow.)
Constraints
The IAM Identity Center SCIM implementation has the following constraints for this API operation.
-
At this time, the
ListGroups
API is only capable of returning up to 50 results. -
Supported filter combinations: (
displayName
), (externalId
), (id
andmember
), and (member
andid
). Note that the use of id as an individual filter, while valid, should be avoided as there is already a getGroup endpoint available. -
Supported comparison operator in filters:
eq
-
Filter must be specified as:
<filterAttribute> eq "<filterValue>"
Errors
The following IAM Identity Center SCIM implementation errors are common for this API operation.
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 |
UnauthorizedException |
Authorization header is invalid or missing. This error also occurs if the tenant ID is incorrect. | 401 |
AccessDeniedException |
Operation is not permitted based on the supplied authorization. | 403 |
ResourceNotFoundException |
When filter querying with a nonexisting member. | 404 |
ThrottlingException |
Too many requests exceeded the limits. | 429 |
InternalServerException |
Service failed to process the request. | 500 |
Examples
Following are example requests and responses for this API operation.
Example Request
GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups User-Agent: Mozilla/5.0 Authorization: Bearer <bearer_token>
Example Response
HTTP/1.1 200 Date: Thu, 23 Jul 2020 00:37:15 GMT Content-Type: application/json x-amzn-RequestId: e01400a1-0f10-4e90-ba58-ea1766a009d7 { "totalResults": 6, "itemsPerPage": 6, "startIndex": 1, "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "Resources": [ { "id": "90677c608a-ef9cb2da-d480-422b-9901-451b1bf9e607", "externalId": "702135", "meta": { "resourceType": "Group", "created": "2020-07-22T23:10:21Z", "lastModified": "2020-07-22T23:10:21Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Foo", "members": [] }, { "id": "90677c608a-95aca21b-4bb7-4161-94cb-d885e2920414", "meta": { "resourceType": "Group", "created": "2020-07-23T00:16:49Z", "lastModified": "2020-07-23T00:16:49Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Beta", "members": [] }, { "id": "90677c608a-00dbcb72-e0b2-49a0-86a2-c259369fc6a7", "meta": { "resourceType": "Group", "created": "2020-07-23T00:18:08Z", "lastModified": "2020-07-23T00:18:08Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Omega", "members": [] }, { "id": "90677c608a-10d47528-1e68-4730-910e-c8a102121f47", "meta": { "resourceType": "Group", "created": "2020-07-22T22:58:48Z", "lastModified": "2020-07-22T22:58:48Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Bar", "members": [] }, { "id": "90677c608a-6ba7b52f-67e5-4849-b64c-15464fe7893b", "meta": { "resourceType": "Group", "created": "2020-07-23T00:14:19Z", "lastModified": "2020-07-23T00:14:19Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Delta", "members": [] }, { "id": "90677c608a-a9f17294-7931-41a5-9c00-6e7ace3c2c11", "meta": { "resourceType": "Group", "created": "2020-07-23T00:20:08Z", "lastModified": "2020-07-23T00:20:08Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Gamma", "members": [] } ] }
Filter examples
For the ListGroup endpoint we support three different combinations of filters as follows:
-
displayName
-
externalId
-
id
andmember
-
member
andid
The filters can be applied in the formats as shown.
Single filter
filter=<filterAttribute> eq "<filterValue>"
Two filters
filter=<filterAttribute1> eq "<filterValue1>" and <filterAttribute2> eq "<filterValue2>"
See the following examples.
displayName
Example Request
GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?filter=displayName eq "Group Bar" User-Agent: Mozilla/5.0 Authorization: Bearer <bearer_token>
Example Response
HTTP/1.1 200 Date: Wed, 22 Jul 2020 23:06:38 GMT Content-Type: application/json x-amzn-RequestId: 45995b44-02cd-419f-87f4-ff8fa323448d { "totalResults": 1, "itemsPerPage": 1, "startIndex": 1, "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "Resources": [ { "id": "90677c608a-10d47528-1e68-4730-910e-c8a102121f47", "meta": { "resourceType": "Group", "created": "2020-07-22T22:58:48Z", "lastModified": "2020-07-22T22:58:48Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Bar", "members": [] } ] }
externalId
Example Request
GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?filter=externalId eq "705167" User-Agent: Mozilla/5.0 Authorization: Bearer <bearer_token>
Example Response
HTTP/1.1 200 Date: Wed, 22 Jul 2020 23:06:38 GMT Content-Type: application/json x-amzn-RequestId: 45995b44-02cd-419f-87f4-ff8fa323448d { "totalResults": 1, "itemsPerPage": 1, "startIndex": 1, "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "Resources": [ { "id": "90677c608a-ef9cb2da-d480-422b-9901-451b1bf9e607", "externalId": "702135", "meta": { "resourceType": "Group", "created": "2020-07-22T23:10:21Z", "lastModified": "2020-07-22T23:10:21Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Foo", "members": [] } ] }
Group id and members
Both group id
and members
are interchangeable in
order.
Example Request
GET https://scim.us-east-1.amazonaws.com/{tenant_id}/scim/v2/Groups?filter=id eq "90677c608a-a9f17294-7931-41a5-9c00-6e7ace3c2c11" and members eq "90677c608a-787142a0-3f27-4cd3-afb6-8aed7ce87094" User-Agent: Mozilla/5.0 Authorization: Bearer <bearer_token>
Example Response
HTTP/1.1 200 Date: Wed, 22 Jul 2020 23:06:38 GMT Content-Type: application/json x-amzn-RequestId: 65d18c02-fc7c-4f2b-9410-ed417acf4fb2 { "totalResults": 1, "itemsPerPage": 1, "startIndex": 1, "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "Resources": [ { "id": "90677c608a-a9f17294-7931-41a5-9c00-6e7ace3c2c11", "meta": { "resourceType": "Group", "created": "2020-07-23T00:20:08Z", "lastModified": "2020-07-23T00:20:08Z" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "Group Gamma", "members": [] } ] }