HomeProduct documentationGitHubCyberArk developer community

Manage Groups with SCIM Endpoints

This topic describes how to manage groups with SCIM endpoints.

Suggest Edits

API-Testing applications can edit groups in the Vault through SCIM group endpoints. This includes:

  • GET: access group information
  • POST: add new group
  • PUT: update group or assign users to group
  • DELETE: delete group

Examples

📘

Managing Privilege Cloud Groups

If the SCIM service user sending the request is in a role with the Vault Management administrative right, the response will includes either Privilege Cloud or PAS Groups, depending on which product you integrated with.

GET all groups

https://mytenant.my.idaptive.app/scim/groups`

This endpoint returns the information of all the groups of the vault. Group names, users involved in the group, and group specifications are outlined in the response.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 2,
    "Resources": [
        {
            "disptlayName": "myGroup1",
            "members": [
                {
                    "value": "1",
                    "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/1",
                    "display": "myUser1"
                },
                {
                    "value": "2",
                    "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/2",
                    "display": "myUser2"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "1",
            "meta": {
                "resourceType": "Group",
                "created": "2021-07-20T18:29:50.9202807Z",
                "lastModified": "2021-07-20T18:29:50.9202807Z",
                "location": "https://mytenant.my.idaptive.app/scim/v2/Group/1"
            }
        },
        {
            "displayName": "myGroup2",
            "members": [
                {
                    "value": "3",
                    "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/3",
                    "display": "myUser3"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "2",
            "meta": {
                "resourceType": "Group",
                "created": "2021-07-20T18:29:50.9202807Z",
                "lastModified": "2021-07-20T18:29:50.9202807Z",
                "location": "https://mytenant.my.idaptive.app/scim/v2/Group/2"
            }
        }
    ]
}

All group provisioning endpoints use a header with bearer token and a tenant ID to navigate to the correct endpoint. The bearer token is listed in Actions in your SCIM App Settings, or you can use the same bearer token as the one used in the User Provisioning section.

This request might return a large number of results. If you want to limit the results, you could use ?startIndex={{integer}}&count={{integer}} to control pagination. For example:

https://mytenant.my.idaptive.app/scim/groups?startIndex=1&count=5

GET group by ID

Sample call:

Request: {{idaptivebaseurl}}scim/Groups/8 

{
"displayName": "Auditors",
"members": [
{ "value": "3", "$ref": "https://aax5785.my.idaptive.qa/Scim/v2/Users/3", "display": "Auditor" }
,
{ "value": "20", "$ref": "https://aax5785.my.idaptive.qa/Scim/v2/Users/20", "display": "TelemetryUser" }
,

{ "value": "22", "$ref": "https://aax5785.my.idaptive.qa/Scim/v2/Users/22", "display": "lcm223p_admin" }
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:cyberark:1.0:Group"
],
"id": "8",
"meta":

{ "resourceType": "Group", "created": "2022-04-12T09:21:40.2319276Z", "lastModified": "2022-04-12T09:21:40.2319276Z", "location": "https://aax5785.my.idaptive.qa/Scim/v2/Group/8" }
,
"urn:ietf:params:scim:schemas:cyberark:1.0:Group":

{ "directoryType": "Vault" }
}

🚧

Note

GET Group by Name is available.

GET sort

[Available with 12.2 PVWA]

https://mytenant.my.idaptive.app/scim/groups?SortBy=displayName&SortOrder=ascending
https://mytenant.my.idaptive.app/scim/groups?SortBy=displayName&SortOrder=descending

Group filter Syntax: [Available with 12.2 PVWA]
https://mytenant.my.idaptive.app/scim/groups?filter=displayName eq 'myGroupName'

POST one group

https://mytenant.my.idaptive.app/scim/groups

This request creates a group and optionally adds a user to that group. More than one user can be added to a created group as long as all of the user IDs are listed as members of the group.

{
    "displayName": "myGroup",
    "members": [
        {
            "value": "1",
            "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/1",
            "display": "myUser1"
        },
        {
            "value": "2",
            "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/2",
            "display": "myUser2"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ]
}

{
    "displayName": "myGroup",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "1",
    "meta": {
        "resourceType": "Group",
        "created": "2021-07-20T18:42:49.4330635Z",
        "lastModified": "2021-07-20T18:42:49.4330635Z",
        "location": "https://mytenant.my.idaptive.app/scim/v2/Group/1"
    }
}

PUT one group

https://mytenant.my.idaptive.app/scim/groups/1

This request navigates to a specific group endpoint through the group ID and changes an informational aspect about the group or user associated with the group. The PUT one group method replaces an existing group with an updated version, or creates a new group entirely. 

{
            "displayName": "myGroup",
            "members": [
                {
                    "value": "1",
                    "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/1",
                    "display": "myUser1"
                },
                {
                    "value": "2",
                    "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/2",
                    "display": "myUser2"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "1",
            "meta": {
                "resourceType": "Group",
                "created": "2021-07-20T18:35:49.7217882Z",
                "lastModified": "2021-07-20T18:35:49.7217882Z",
                "location": "https://mytenant.my.idaptive.app/scim/v2/Group/1"
            }
        }

{
    "displayName": "myGroup",
    "members": [
        {
            "value": "1",
            "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/1",
            "display": "myuser1"
        },
        {
            "value": "2",
            "$ref": "https://mytenant.my.idaptive.app/scim/v2/Users/2",
            "display": "myuser2"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "1",
    "meta": {
        "resourceType": "Group",
        "created": "2021-07-20T18:37:17.7326579Z",
        "lastModified": "2021-07-20T18:37:17.7326579Z",
        "location": "https://mytenant.my.idaptive.app/scim/v2/Group/1"
    }
}

PUT requests edit the same amount of information as POST requests.

DELETE one group

https://mytenant.my.idaptive.app/scim/groups/1

DELETE one group deletes a group. The request uses a group ID to locate the group's endpoint. DELETE one group is the only request that returns no information in the HTTP response body. Requesting DELETE twice will yield an error, since the group ID no longer exists.

Deleting a group will not delete the users involved, but will delete the connections the users have to the nonexistent group.

Updated about 1 year ago