Manage users with SCIM endpoints

This topic describes how to provision users from a SCIM-compliant client (for example, a human capital management system) to a CyberArk Vault.

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

• GET: access user information

• POST: create a new user

• PUT: update all information for an existing user

• PATCH: update only specific information for an existing user

• DELETE: delete a user

• LINKEDOBJECT

The CyberArk Identity SCIM server supports the SCIM User core schema. For user objects that are not part of the SCIM User code schema and require management of additional custom attributes, the CyberArk Identity SCIM server provides custom schema support (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.

To test 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 that you must specify the SCIM schema in the request payload before using a custom SCIM schema. See the examples in this topic for more information.

SCIM endpoint query syntax

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

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

where <baseURL> is the tenant URL.

Example:

Query operators

SCIM endpoints for user queries support the following operators:

Query attributes

SCIM endpoints for user queries support the following attributes:

Sort a list of users

You can sort a list of users in ascending or descending order. The SCIM endpoint for sorting uses the following format:

<baseURL>/scim/users?sortBy=<attribute>&sortOrder=<ascending or descending>

where <baseURL> is the tenant URL.

Example:

Enable pagination when querying users

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

<baseurl>/scim/users?startIndex=<number>&count=<number-of-items-to-retrieve>

where <baseURL> is the tenant URL.

Example:

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

Examples

See the following examples for common requests to user resources.

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": "userreview7@cyberark.cloud.979",

"password": "testTEST1234",

"name": {

"givenName": "automation_user"

}

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

{
	"name": {

GET all users

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

This endpoint allows you to obtain information relating to all users in the 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 myUser@example.com:

https://mytenant.my.idaptive.app/scim/v2/Users/?filter=userName eq "myUser@example.com"

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": "myUserName@example.net",
			"name": {
				"formatted": "myFormattedName",
				"givenName": "myGivenName"
			},
			"displayName": "myDisplayName",
			"active": true,
			"emails": [
				{
					"type": "work",
					"primary": true,
					"value": "myemail@example.net"
				}
			],
			"schemas": [
				"urn:ietf:params:scim:schemas:extension:enterprise: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"
			}
			"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
				"manager": {
				"value": "090ba783-4c6b-4e0a-b531-b122b3c38a48",
				"displayName": "scTest1manager@cyberark.cloud.63255"							
		}
	]
}

GET one user [available with PVWA 12.2]

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

Each user object has a unique user ID (id attribute) 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": "myUserName@example.net",
	"name": {
		"formatted": "myFormattedName",
		"givenName": "myGivenName"
	},
	"displayName": "myDisplayName",
	"active": true,
	"emails": [
		{
			"type": "work",
			"primary": true,
			"value": "myemail@example.net"
		}
	],
	"schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:User",
	],
	"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 PVWA 12.2]

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

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

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

lastname > givenName https://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.givenNamehttps://mytenant.my.idaptive.app/scim/v2/Users?sortBy=name.givenName&sortOrder=ascendinghttps://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 the 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": "myusername@example.com",
	"name": {
		"givenName": "myGivenName"
	},
	"displayName": "myDisplayName",
	"active": true,
	"emails": [
		{
			"type": "work",
			"primary": true,
			"value": "myemail@example.com"
		}
	],
	"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"
	}
}

PATCH

A PATCH request updates only specific values for a user.

The following example shows a successful PATCH response (200 HTTP code).

{

The following example shows the response for an invalid PATCH request (400 HTTP code).

{

The following example shows a PATCH request updating a username.

{

The following example shows a PATCH request updating a user's status.

{

The following example shows an alternative PATCH method for updating a user's status.

{

The following example shows a PATCH request updating a user's DisplayName.

{

The following example shows a PATCH request updating a user's formatted name.

{

The following example shows a PATCH request updating a user's given name.

{

The following example shows a PATCH request updating a user's family name.

{

The following example shows a PATCH request updating a user's preferred language.

{

The following example shows a PATCH request updating a user's password.

{

The following example shows a PATCH request updating a user's email address.

{

The following example shows an alternative method for using PATCH to update a user's email address.

{

The following example shows a PATCH request updating a user's work phone number.

{

The following example shows a PATCH request updating a user's mobile phone number.

{

The following example shows a PATCH request updating a user's home phone number.

{

The following example shows a PATCH request updating a user's custom attribute.

{

The following example shows a PATCH request updating the user's manager.

{

The following example shows a PATCH request updating a user's organization.

{

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

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

Use LINKEDOBJECT if users are present in the LDAP/vault.

LINKEDOBJECT user example response:

{
	"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": "\"
	}
},