Creating a User for NSX CLI and assigning API roles/permissions

Products

• VMware NSX

Issue/Introduction

This article provides steps to create an NSX CLI user which can be used only for running API calls against the NSX Manager.

By Default, in a standard NSX installation, the only account which only has API privileges (no vSphere Web Client privileges) is the NSX Manager admin account. It is possible to use the vSphere SSO accounts to interact with the NSX API, however, this will also allow vSphere Web Client access (although they would not be able to view or access anything once logged in without granting specific vCenter Server rights).

When an API is run from an SSO user, the audit logs will show that the admin account has completed the API (not the specific user). By creating a specific API roles, users can audit their environment and know exactly where APIs were ran from.

Environment

VMware NSX for vSphere 6.1.x
VMware NSX for vSphere 6.2.x

Resolution

To create an NSX CLI user:

1. Create the user on the NSX CLI, and assign the correct permissions. To do this, go to the NSX Manager VM in the vSphere Client and open a vSphere console. Press enter on the console window to see the command prompt. Log in as admin and run these commands:
   
   enable
   configure terminal
    
2. Create the user on the NSX CLI, and assign the correct permissions, then write the changes. In the example below, replace "api_username" and "<password" with your preferred username and password. 
   
   nsxmgr(config)#
   nsxmgr(config)# user api_username password plaintext <password>
   nsxmgr(config)#
   nsxmgr(config)# user api_username privilege web-interface
   nsxmgr(config)# exit
   nsxmgr#
   nsxmgr# write memory
   
   Note: If you see the following error message after running the second command, contact Broadcom Support. 
   
   ERROR: could not add privilege.
    
3. Verify that user has been created.
   
   nsxmgr#
   nsxmgr# show running-config
   Building configuration...
   Current configuration:
   !
   user api_username
   !
   ntp server au.pool.ntp.org
   !
   ip name server 10.10.3.24
   !
   hostname nsxmgr
   !
   interface mgmt.
   ip address 10.10.3.4/24
   !
   ip route 0.0.0.0/0 10.10.3.1
   !
   web-manager
   nsxmgr#
    
4. Create a new user through API so that it appears as created by the CLI. Ensure to start the new user as an auditor so it can be modified later. Any compatible REST client can be used, for example Postman, RESTClient or curl. For more information, see the NSX for vSphere API Guide.
   
   POST https://<NSXMGR_IP>/api/2.0/services/usermgmt/role/<userId>?isCli=true
   
   <accessControlEntry>
   <role>new-role</role>
   <resource>
   <resourceId>resource-num</resourceId>
   </resource>
   </accessControlEntry>
   
   Example 1:
   
   POST https://<NSXMGR_IP>/api/2.0/services/usermgmt/role/api_username?isCli=true
   <accessControlEntry>
   <role>auditor</role>
   <resource>
   <resourceId>globalroot-0</resourceId>
   </resource>
   </accessControlEntry>
   
   Example 2:
   
   Continuing with the previous example from step 1, here is what the command would look like for curl:
   
   curl -v -H "Content-Type:application/xml" -k -u admin -X POST -d "<accessControlEntry><role>auditor</role><resource><resourceId>globalroot-0</resourceId></resource></accessControlEntry>" https://<NSXMGR_IP>/api/2.0/services/usermgmt/role/api_username?isCli=true
    
5. Verify that there is now a user created in the NSX Manager GUI and shows that its origin is the NSX CLI User. Navigate to Networking and Security > NSX Managers > NSX Manager IP > Manage > Users. Note; For NSX for vSphere 6.4.x, navigate to Networking and Security > Users and Domains. Here is an example screenshot which indicates the account was created successfully.
   
   
   
   You can now change the role of that user in the GUI or you can run the following API to modify that user.
   
   PUT https://<NSXMGR_IP>/api/2.0/services/usermgmt/role/<userId>
   <accessControlEntry>
   <role>role</role>
   <resource>
   <resourceId>resource-num</resourceId>
   </resource>
   </accessControlEntry>
   
   For example:
   
   PUT https://<NSX-Manager-IP>/api/2.0/services/usermgmt/role/api_username
   
   <accessControlEntry>
   <role>enterprise_admin</role>
   <resource>
   <resourceId>globalroot-0</resourceId>
   </resource>
   </accessControlEntry>
   possible roles:
   super_user (System Administrator)
   vshield_admin (NSX Administrator)
   enterprise_admin(Enterprise Admin)
   security_admin (Security Administrator)
   auditor (Auditor)

Additional Information