Setting user principal name (UPN) via Rest API

Products

• CA Privileged Access Manager (PAM)

Issue/Introduction

You have PKI users for which you want to provision group memberships and access policies upfront. To do so you provision local users with authentication type "cac" using Rest API resource "POST /api.php/v1/users.json". You understand that PAM can use two properties in the certificate to match it with an existing user entry, the subject name, and, if available, the user principal name that most certificates include in the subject alternate names (SAN) list. The API Docs page does not document any parameter to set the UPN. How can you set it using the Rest API? 

Environment

Any PAM server with the Rest API enabled.

Resolution

Use parameter "userPrincipalName":

Sample body:

{
    "authType":"cac",
    "email":"[e-mail]",
    "firstName":"Api",
    "lastName":"User1",
    "userPrincipalName":"[e-mail]",
    "userName":"CN=Api User1,CN=Users,DC=example,DC=com"
}

Additional Information

For existing local users you can update the UPN using the "PUT /api.php/v1/users.json" resource with a body similar to the following:

{
    "userId":"<userID>",
    "userPrincipalName":"[e-mail]"
}

<userID> is the ID of the user that is returned by the POST call and can be retrieved later on using GET calls.

Note that there was a problem in releases up to 4.2.0, where the PUT call failed, if the user currently did NOT have a user principal name. This problem should be fixed from 4.2.1 on.