ListGroups - IAM Identity Center SCIM Implementation
Not supportedConstraintsErrorsExamplesFilter examples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 and ListGroups return an empty member list. To see group info for a certain member, call ListGroups 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 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.

  • 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 and member

  • member and id

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": []
        }
    ]
}