Perform generic user functions

This topic describes how to perform the generic user functions that CyberArk Identity provides, which you can apply to any Identity Service user (Cloud Directory user, AD/LDAP user, or federated user). The generic user functions include the following:

  • Contact users for access to Identity Platform

  • Get information about a user or users

  • Configure authentication for users; for example, set a security question or reset password

For a complete list of generic user functions, see /UserMgmt functions in the API reference guide.

Invite users to the portal

The API enables you to invite users, via an SMS message or email, to log into the portal. This section shows how to invite a set of AD users by calling the /UserMgmt/InviteUsers function. You could use the same process to send an invite to Cloud Directory users or LDAP users.

You need the name and UUID for each user to invite. Use a query such as the following on the DSUsers table to retrieve the AD users to invite.

To authenticate AD/LDAP users to CyberArk Identity, you need a cloud connector to establish and maintain communication between CyberArk Identity and the AD or LDAP repository. This section assumes that you have a functioning cloud connector for your service. For more information, see Install the CyberArk Identity Connector.

/Redrock/Query
{
	"Script": "Select DisplayName, InternalName from DSUsers Where "ServiceInstance = 'acmeAD.com'  ORDER BY InternalName COLLATE NOCASE"
}

The query returns the name (DisplayName) and UUID (InternalName) for every user in the acmeAD.com Active Directory domain.

DSUsers query response 

"FullCount": 72,
"Results": [
	{
		"Entities": [
			{
				"Type": "DsUsers",
				"Key": "23a3d71e-ef74-1034-9268-cfacde932ec3",
				"IsForeignKey": false
			},
		],
		"Row": {
			"DisplayName": "michael1",
			"InternalName": "23a3d71e-ef74-1034-9268-cfacde932ec3"
		}
	},
	{
		"Entities": [
			{
				"Type": "DsUsers",
				"Key": "37e02ca0-ef74-1034-9269-cfacde932ec3",
				"IsForeignKey": false
			},
		],
		"Row": {
			"DisplayName": "michael2",
			"InternalName": "37e02ca0-ef74-1034-9269-cfacde932ec3"
			}
		},
   
		{
		"Entities": [
			{
				"Type": "DsUsers",
				"Key": "57234e80-ef74-1034-926a-cfacde932ec3",
				"IsForeignKey": false
			},
		],
		"Row": {
			"DisplayName": "michael3",
			"InternalName": "57234e80-ef74-1034-926a-cfacde932ec3"
			}
		},
		{
		"Entities": [
			{
				"Type": "DsUsers",
				"Key": "76f995e8-ef74-1034-926b-cfacde932ec3",
				"IsForeignKey": false
			},
				],
				"Row": {
				"DisplayName": "michael4",
				"InternalName": "76f995e8-ef74-1034-926b-cfacde932ec3"
		}
	},
...

Now, invite the users retrieved from the query by passing the name and UUID retrieved from the query to /UserMgmt/InviteUsers:

If you were adding LDAP groups instead of users, you could send a group email by passing GroupInvite: true, but since you are not, set it to false.* 

/UserMgmt/InviteUsers
{
"Entities": [
   
	{'Type': 'User',
	'Name': 'michael1',
	'Guid': '23a3d71e-ef74-1034-9268-cfacde932ec3'
	},
	{
	'Type': 'User',
	'Name': 'michael2',
	'Guid': '37e02ca0-ef74-1034-9269-cfacde932ec3'
	},
	{
	'Type':'User',
	'Name':'michael3',
	'Guid': '57234e80-ef74-1034-926a-cfacde932ec3'
	},
	{
	'Type':'User',
	'Name':'michael4',
	'Guid': '76f995e8-ef74-1034-926b-cfacde932ec3'
	}
],
"EmailInvite": true,
"SmsInvite": false,
"GroupInvite": false,
"Role": "Invited Users"
}

The function sends an email message, with a login link, to each of the specified users. The server adds each user to the User Table . You can manage these users in the same way as Cloud users; for example, by adding them to roles, retrieving information, resetting the password, and so on.

Get information for users

To retrieve information for a user, you need the name or UUID of the user. For example, to retrieve information about a user, make a call to /UserMgmt/GetUserAttributes. Note that you can specify the ID for the user or the user's name for the ID (as shown here):

/UserMgmt/GetUserAttributes
{
	"ID": "auserm@gmail"
}

/UserMgmt/GetUserAttributes sample response 

{
	"success": true,
	"Result": {
		"Description": "",
		"ForcePasswordChangeNext": "False",
		"DisplayName": "Allen Usem",
		"EmailAddress": "auserm@gmail.com",
		"LoginName": "auserm@gmail.com",
		"UserAttributes": {
			"Description": "",
			"DisplayName": "Allen Usem",
			"FirstName": "Allen",
			"PartnerNameList": "[\"Google\"]",
			"Email": "auserm@gmail.com",
			"LastName": "Userm",
			"userprincipalname": "auserm@gmail.com",
			"UserId": "107354040926934871406"
		},
		"DistinguishedName": "/C30B30B1-0B46-49AC-8D99-F6279EED7999/EF46F24B-3D37-489B-A9D7-C1ECC38A3788/076e4b41-5846-91f0-108a-9fc0ba17e02b",
		"UserPrincipalName": "auserm@gmail.com",
		"DirectoryServiceUuid": "C30B30B1-0B46-49AC-8D99-F6279EED7999",
		"InEverybodyRole": true,
		"MobileNumber": "",
		"Locked": false,
		"LastPasswordChangeDate": "/Date(1458323296643)/",
		"OfficeNumber": "",
		"FederationName": "Google",
		"HomeNumber": null,
		"FederationUuid": "EF46F24B-3D37-489B-A9D7-C1ECC38A3788",
		"PartnerName": "Google",
		"SourceDsName": "Google",
		"SourceDsType": "FDS",
		"CurrentState": "None",
		"Uuid": "076e4b41-5846-91f0-108a-9fc0ba17e02b",
		"CanonicalName": "auserm@gmail.com",
		"State": "None"
	},
	"Message": null,
	"MessageID": null,
	"Exception": null,
	"ErrorID": null,
	"ErrorCode": null,
	"InnerExceptions": null
}

You can also retrieve specific information about a user account by calling any of the following functions:

  • /UserMgmt/GetUserPicture to retrieve a user's picture.

  • /UserMgmt/GetUserHierachy to retrieve the management chain for a user.

  • /UserMgmt/GetUserRolesAndAdministrativeRights to retrieve a list of roles and rights for a user.

For example, to retrieve a user's picture:

/UserMgmt/GetUserPicture
{
"ID": "auserm@gmail.com"
}

Search for users

To search for users, send a POST request to the /UserMgmt/DirectoryServiceQuery endpoint. You can search for users in any directory service using the typed string attribute filter _like in the request payload (searches by prefix). In addition, you can search for CyberArk Identity Directory users with the typed string attribute filter _end (searches by suffix). The following attributes support these filters:

  • Email

  • DisplayName

  • SystemName

  • Description

Example search

See the following request payload for an example of searching for users with the Email suffix example.com. The example uses the _end filter with the Email attribute, and limits the search to the CyberArk Identity Directory by specifying the CyberArk Identity Directory UUID.

You can get the CyberArk Identity Directory UUID with a POST request to {{baseUrl}/Core/GetDirectoryServices.

{
	"user": "{\"Email\": {\"_end\":\"example.com\"}}",
	"directoryServices": [
		"09B9A9B0-6CE8-465F-AB03-65766D33B06E"
	]
}

The response includes a count of the number of records returned as well as detailed results. Note that parts of the response example are excluded for brevity.

"FullCount": 1,
	"Results": [
		{
			"Entities": [
				{
					"Type": "af5b4a3f-e5d7-4801-a055-15cfa75ad6af",
					"Key": "User",
					"IsForeignKey": false
				}
			],
			"Row": {
					"DistinguishedName": "sales0@example.com",
					"ServiceType": "CDS",
					"Locked": false,
					"ObjectType": "User",
					"DisplayName": "sales0",
					"Status": "Not Invited",
					"StatusEnum": "Created",
					"ServiceInstance": "CDS",
					"ServiceInstanceLocalized": "Idaptive Directory",
					"SystemName": "sales0@example.com",
					"Description": null,
					"EMail": "sales0@example.com",
					"InternalName": "af5b4a3f-e5d7-4801-a055-15cfa75ad6af",
					"Forest": "",
					"DirectoryServiceUuid": "09B9A9B0-6CE8-465F-AB03-65766D33B06E",
					"Enabled": true
					}
				}
			],
			"ReturnID": ""
		}
	},
	"Message": null,
	"MessageID": null,
	"Exception": null,
	"ErrorID": null,
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}