Manage groups with SCIM endpoints

This topic describes how to get API testing applications to manage 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

  • PATCH: update only specific information for an existing group

  • DELETE: delete group

SCIM endpoint query syntax

Use SCIM endpoints to enter queries that retrieve groups based on attributes. Each query contains an operator, an attribute, and an attribute value in the following format:

<baseURL>/scim/Groups?filter=<attribute> <operator> "<attributeValue>"

where <baseURL> is the tenant URL.

Example:

https://mytenant.my.idaptive.app/scim/Groups?filter=displayName eq "Example Display Name"

Query operators

SCIM endpoints for querying groups support the following operators:

Group query operators

Operators

Meaning

eq

equals

sw

starts with

co

contains

ew

ends with

Query attributes

SCIM endpoints for querying groups support the following attributes:

Group query attributes

Attribute

Description

displayName

Uniquely identifies a group based on the group display name

For PAM - Self-Hosted, only the eq filter is supported for this attribute.

id

Uniquely identifies a group based on the group ID

members.display

Returns a list of groups of which a user (filtered by username) is a member

members.value

Returns a list of groups of which a user (filtered by user ID) is a member

For PAM - Self-Hosted, the id, members.display, and members.value attributes are not supported.

Enable pagination when querying groups

To enable pagination when querying groups, use the following format:

https://<baseURL>/scim/groups?startIndex=<number>&count=<number-of-items-to-retrieve>

where <baseURL> is the tenant URL.

Example:

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

The parameter 1&count=100 retrieves the first 100 items in the results. To view additional results, send another request. For example, this request gets items 101 to 201:

https://mytenant.my.idaptive.app/scim/groups?startIndex=101&count=100

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 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": [
        {
            "displayName": "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 a 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" }
}

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

POST one group

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

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

Request:

{
    "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"
    ]
}

Response:

{
    "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.

Request:

{
    "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"
    }
}

Response:

{
    "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.

PATCH

A PATCH request updates only specific values for a group.

{

"schemas": [

"urn:ietf:params:scim:api:messages:2.0:PatchOp"

],

"Operations": [

{

"op": "add",

"path": "members",

"value": [

{

"value": "446cd9c1-0ff2-433d-90d2-dd9507082fbf",

"type": "User"

}

]

},

{

"op": "replace",

"path": "displayname",

"value": "Privilege OnPrem"

}

]

}

 

DELETE one group

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

The DELETE one group request deletes a group, using 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, because 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.