Create Active Directory target accounts using the Rest API
Article ID: 221735
Updated On:
Products
Issue/Introduction
You are having trouble creating new accounts for an Active Directory target application in a device using the CAPAM API. The specific URL is:
POST /api.php/v1/devices.json/{deviceId}/targetApplications/{applicationId}/targetAccounts
The error you receive when submitting a body, appId, and deviceId is:
{
"error": {
"code": 400,
"message": "Bad Request: PAM-CMN-0467: A Password Authority problem prevented completing the request. Message: PAM-CM-0789: The password change process was not specified. The value assigned to the 'useOtherAccountToChangePassword' attribute must be 'true' or 'false'. Check log for details."
}
}
This is the body you are using for it, with the Ids removed/replaced:
{"deviceId":"17966003","applicationId":"38001","accountName":"newaccount","password":"xxxx"}
You have tried using the “useOtherAccountToChangePassword” attribute and the service account as suggested from the error without any luck.
Cause
The above body has multiple problems. It incorrectly includes the device and target application ids, which are part of the Rest URL, not part of the body. And it is missing required attributes for the target application, in this case of type Active Directory.
Resolution
The API Docs page for the "POST /api.php/v1/devices.json/{deviceId}/targetApplications/{applicationId}/targetAccounts" only documents account parameters common to all types of target accounts. The only two required common parameters are "accountName" and "password". Other parameters, such as "synchronize" (default "f") or "privileged" (default "f") are optional.
There are too many target application specific attributes to document on the API Docs page. The list of attributes specific to a given target application type is found in PAM online documentation under Implementing > Protect Privileged Account Credentials > Identify Target Applications and Connectors, on the page that discusses the CLI configuration. This refers to the remote CLI, the traditional API used to add target applications and accounts.
E.g. for the Active Directory target connector we need to review page Active Directory Target CLI Configuration. On this page we will find that the following attributes are required:
Attribute.extensionType - always required
Attribute.userDN - always required
Attribute.useOtherAccountToChangePassword - always required
Attribute.otherAccount - required if useOtherAccountToChangePassword is true
So now we know that we need parameters "accountName", "password", and an "attributes" list with at least "extensionType", "userDN" and "useOtherAccountToChangePassword". If the latter is "true", we also need "otherAccount". Below is a sample body that will create a synchronized privileged Active Directory target account, which has its password changed by another account.
{ "accountName":"restuser249", "password":"mycurrentpwd", "attributes":{ "extensionType":"windowsDomainService", "userDN":"CN=Rest User249,CN=Users,DC=example,DC=com", "useOtherAccountToChangePassword":"true", "otherAccount":"1036001" }, "synchronize":"t", "privileged":"t"}
The ID for "otherAccount" was obtained from the "GET /api.php/v1/devices.json/{deviceId}/targetApplications/{applicationId}/targetAccounts" Rest API resource.
Note that if you set the "synchronize" attribute to true, "t", the password has to be the current correct password. If the password cannot be verified, account creation will fail. As of August 2021 only the Windows Remote target application supports a "forcePasswordChange" attribute that can set a new password if the current one is not known and another account can perform the password change.
Additional Information
As of March 2023 there is a known limitation in that the Rest API cannot be used to set field "Access Type" in the target account. Any Rest API call to create or update a target account will blank this field out, see KB 256241.
Feedback
