Manage Users with SCIM Endpoints

CyberArk Identity allows you to manage User objects in the Vault through the scim/Users/ endpoint. Supported requests include:

• GET: access user information
• POST: add new users
• PUT: update the information of existing users
• DELETE: delete users
• LINKEDOBJECT

Note that these CyberArk Identity SCIM server endpoints are available to manage Vault users only and not any other CyberArk Identity -connected directories like Active Directory, LDAP, Azure AD or Google Directory Services.

The CyberArk Identity SCIM server supports the SCIM User core schema. To address use cases which need management of additional custom attributes for user objects that are not part of the SCIM User core schema, the CyberArk Identity SCIM server provides support for the custom schema (urn:scim:schemas:extension:custom:2.0).

In addition, CyberArk Identity supports attributes defined by the LinkedObject schema. These attributes are available only through GET requests - you can't modify them. Refer to https://tools.ietf.org/id/draft-grizzle-scim-pam-ext-01.html#linked-object for more information.

For testing the above methods, you need to send a header with a bearer token for authentication (retrieved through Actions in your SCIM App Settings) and a tenant ID for navigating to the correct endpoint. When you update User attributes using the Users/ endpoint, be sure to specify the schema in the request payload.

Supported core schema attributes

The CyberArk Identity SCIM server supports the following core schema attributes.

Custom schema requirements

Note the following pre-requisites for using the custom SCIM schema.

• The SCIM schema must be specified in the request payload.
  Refer to the examples in this topic for more information.

Examples

Refer to the following examples for common requests to User resources.

📘

Managing Privilege Cloud Users

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

POST one user

https://mytenant.my.idaptive.app/scim/v2/Users

With the POST method, you can add users with core and custom attributes.

Include the SCIM schema in the request payload, as shown in the following example.

{
    "userName": "[email protected]",
    "name": {
        "givenName": "exampleuser63"
    },
    "password": "<password>",
    "displayName": "exampleuser63",
    "active": true,
    "emails": [
        {
            "type": "work",
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "urn:scim:schemas:extension:custom:2.0": {
        "Job_Title": "Customer Support Specialist",
        "experience_in_years": 15,
        "gross_salary": 13500.30,
        "is_fresher": false,
        "graduation_date": "2018-03-29T13:34:00.000"
    }
}

Note the id attribute value in the response; you will need this value to make requests specific to this user.

{
    "userName": "[email protected]",
    "name": {
        "formatted": "exampleuser63",
        "givenName": "exampleuser63"
    },
    "displayName": "exampleuser63",
    "active": true,
    "emails": [
        {
            "type": "work",
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:scim:schemas:extension:custom:2.0"
    ],
    "id": "1",
    "meta": {
        "resourceType": "User",
        "created": "2020-11-16T15:54:12.3411274Z",
        "lastModified": "2020-11-16T15:54:12.3411274Z",
        "location": "https://mytenant.my.idaptive.app/scim/v2/Users/1"
    }
}

GET all users

https://mytenant.my.idaptive.app/scim/v2/Users

This endpoint allows you to obtain information relating to all users in Vault, including the user's id attribute that you need for PUT, and DELETE requests.

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/v2/Users?startIndex=1&count=5

If you have a large number of users in your environment, you can filter by core attribute. For example, if you need to find a user's id, but you only know the userName value, you could send the GET request to https://mytenant.my.idaptive.app/scim/v2/Users/?filter=userName eq "{{userName}}". For example, to find the id for [email protected]:

https://mytenant.my.idaptive.app/scim/v2/Users/?filter=userName eq "[email protected]"

If you only know the user's first name, you could filter by the givenName. For example:

https://mytenant.my.idaptive.app/scim/v2/Users/?filter=name.givenName eq "myUserGivenName"

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "itemsPerPage": 1,
    "startIndex": 1,
    "Resources": [
        {
            "userName": "[email protected]",
            "name": {
                "formatted": "myFormattedName",
                "givenName": "myGivenName"
            },
            "displayName": "myDisplayName",
            "active": true,
            "emails": [
                {
                    "type": "work",
                    "primary": true,
                    "value": "[email protected]"
                }
            ],
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:scim:schemas:extension:custom:2.0"
            ],
            "id": "1",
            "meta": {
                "resourceType": "User",
                "created": "2020-11-16T22:55:05.5426621Z",
                "lastModified": "2020-11-16T22:55:05.5426621Z",
                "location": "https://mytenant.my.idaptive.app/scim/v2/Users/1"
            }
        }
    ]
}

GET one user [Available with 12.2 version of PVWA]

https://mytenant.my.idaptive.app/scim/v2/Users/{{id}}

Each user object has a unique user ID (attribute id) generated by the SCIM server, which you can find in the response payload of a GET request to https://mytenant.my.idaptive.app/scim/v2/Users. Adding the id attribute value to the Users endpoint retrieves attributes for just that user.

For example, https://mytenant.my.idaptive.app/scim/v2/Users/1 returns the request response payload for that user as shown below.

{
    "userName": "[email protected]",
    "name": {
        "formatted": "myFormattedName",
        "givenName": "myGivenName"
    },
    "displayName": "myDisplayName",
    "active": true,
    "emails": [
        {
            "type": "work",
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:scim:schemas:extension:custom:2.0"
    ],
    "id": "1",
    "meta": {
        "resourceType": "User",
        "created": "2020-11-16T23:11:26.8196554Z",
        "lastModified": "2020-11-16T23:11:26.8196554Z",
        "location": "https://mytenant.my.idaptive.app/scim/v2/Users/1"
    }
}

GET (sort) [Available with 12.2 version of PVWA]

User sort syntax:
firstname --> familyName
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.familyName
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.familyName&sortOrder=ascending
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.familyName&sortOrder=descending

username
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=userName
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=userName&sortOrder=ascending
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=userName&sortOrder=descending

userType
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=userType
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=userType&sortOrder=ascending
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=userType&sortOrder=descending

lastname --> givenName
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.givenName
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.givenName&sortOrder=ascending
https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.givenName&sortOrder=descending

PUT one user

https://mytenant.my.idaptive.app/scim/v2/Users/{{id}}

Use a PUT request to update all attributes of an existing user. Null values are supported, so you can use a PUT request to remove user attribute values.

PUT requests require the same amount of user information as POST requests.

{
    "userName": "[email protected]",
    "name": {
        "givenName": "myGivenName"
    },
    "displayName": "myDisplayName",
    "active": true,
    "emails": [
        {
            "type": "work",
            "primary": true,
            "value": "[email protected]"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "urn:scim:schemas:extension:custom:2.0": {
        "Job_Title": "Graduate Trainee",
        "experience_in_years": 1,
        "gross_salary": 109.10,
        "is_fresher": false,
        "graduation_date": "2017-06-23T13:34:00.000"
    }
}

DELETE one user

https://mytenant.my.idaptive.app/scim/v2/Users/{{id}}

The DELETE request deletes a single user specified in the SCIM url. You can only delete a single user. Trying to delete all users results in an error.

DELETE is the only request that does not return a response. Running DELETE twice receives an error; you cannot delete a user if the user ID no longer exists in Vault.

LINKEDOBJECT

LINKEDOBJECT https://mytenant.my.idaptive.app/scim/v2/users
Linked object if users are present in LDAP/vault

{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 13,
"itemsPerPage": 13,
"startIndex": 1,
"Resources": [
{
"userName": "usera",
"displayName": "usera",
"userType": "EPVUser",
"active": false,
"entitlements": [
"AddUpdateUsers",
"AddSafes",
"AddNetworkAreas",
"ManageDirectoryMapping",
"ManageServerFileCategories",
"AuditUsers",
"BackupAllSafes",
"RestoreAllSafes",
"ResetUsersPasswords",
"ActivateUsers"
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "22",
"meta": {
"resourceType": "User",
"created": "2020-12-22T10:12:22.942741Z",
"lastModified": "2020-12-22T10:12:22.942741Z",
"location": "\"
}
},
{
"userName": "simis",
"name": {
"familyName": "shabtai",
"givenName": "simi"
},
"displayName": "simis",
"userType": "EPVUser",
"active": false,
"urn:ietf:params:scim:schemas:pam:1.0:LinkedObject": {
"source": "LDAP",
"nativeIdentifier": "CN=simi shabtai,CN=Users,DC=IdaptiveAD,DC=com"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:pam:1.0:LinkedObject"
],
"id": "27",
"meta": {
"resourceType": "User",
"created": "2020-12-22T10:12:22.942741Z",
"lastModified": "2020-12-22T10:12:22.942741Z",
"location": "\"
}
},