How to manage NSX Manager roles w/PowerNSX


Let’s start with the terminology.

  • What are the roles of the NSX Manager? NSX Manager roles allow you to manage access rights to NSX objects by assigning to particular user or group a certain role. In the UI, these settings are in Networking and Security -> System -> Users and Domains.


  • What is PowerNSX? PowerNSX is a PowerShell module that abstracts the VMware NSX RESTful API into a set of easy-to-use PowerShell functions. The PowerNSX module does not contain a ready-made function for managing the NSX Manager roles, but it does have a universal function for accessing the NSX API, the Invoke-NsxRestMethod, which we will use in our script.

  • The Power-NsxRole.ps1 script contains several functions.


Let’s look at each of them.


  • The function Add-NsxEntityRoleAssignment, as its name implies, assigns any role -Role to user(s) -User or group(s) -Group. The -Role parameter is optional and has a default value.
Add-NsxEntityRoleAssignment -User NSXAdmin1@vsphere.local -Role 'System Administrator'
Add-NsxEntityRoleAssignment -Group -Role Auditor
Add-NsxEntityRoleAssignment -User NSXAdmin1@vsphere.local


  • Both the -User and -Group parameters support working with multiple users or groups at once, but not at the same time. Moreover, the objects can be from different sources, for example, one from the SSO domain and the other from Active Directory.
Add-NsxEntityRoleAssignment -User NSXAdmin1@vsphere.local,
Add-NsxEntityRoleAssignment -Group NSXAdmins@vsphere.local,
  • The -User parameter is positional, so if you do not specify the type of objects, the function will consider them as users.
Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local -Role 'Security Administrator'
Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local,
  • This function, like all the others, supports such standard parameters as -Verbose, -Debug and -Confirm. The -Role parameter supports Intellisense Ctrl+Space and you do not need to write or remember the role names.
Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local -Role 'Network Engineer' -Debug -Verbose
Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local, -Confirm:$false
  • Please note that the same user or group can have one role only!
Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local -Role 'Security Administrator'
Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local -Role 'Network Engineer'
  • In order to change the role, you need to first delete the existing one, and then assign a new role. The next function of our script will help us in this.


  • The Remove-NsxEntityRoleAssignment function is very similar to the previous one, it even has the same parameters except for the -Role parameter, since it does not need it. It removes any role assigned to any user(s) -User or group(s) -Group.
Remove-NsxEntityRoleAssignment -User NSXAdmin1@vsphere.local
Remove-NsxEntityRoleAssignment -Group
Remove-NsxEntityRoleAssignment NSXAdmin1@vsphere.local, NSXAdmin2@vsphere.local -Verbose
Remove-NsxEntityRoleAssignment -Group NSXAdmins@vsphere.local, -Confirm:$false



  • The function Add-NsxEntityAccessScope is the highlight of our script, because it allows you to assign not a global role, but a role within a scope (group of NSX objects)! Starting with NSX 6.2, VMware removed the Limit Scope option from the UI, but left it in the API. This situation is well described in this article by Mike Da Costa and the function Add-NsxEntityAccessScope fully automates the solution proposed in his article.
Get-NsxEdge esg_Lab1 | Add-NsxEntityAccessScope -User NSXAdmin1@vsphere.local -Role Auditor -Debug
  • The Add-NsxEntityAccessScope function has one additional parameter -AccessScope that can accept any number of different NSX objects. The objects can be an Edge, DLR or Logical Switch.
Get-NsxEdge esg_Lab1 | Add-NsxEntityAccessScope
Get-NsxLogicalRouter dlr_Lab1 | Add-NsxEntityAccessScope -User NSXAdmin2@vsphere.local –Confirm:$false -Role Auditor
  • Since only one role can be assigned to the same user or group, i.e. add only once; the next trick will allow adding different types of NSX objects to the Access Scope.
$scope = @(Get-NsxEdge esg_Lab1)
$scope += Get-NsxTransportZone trz_Lab | Get-NsxLogicalSwitch
$scope += Get-NsxLogicalRouter dlr_Lab1
Add-NsxEntityAccessScope -AccessScope $scope -Group NSXAdmins@ssolab.local -Confirm:$false


  • Well, finally, the function Get-NsxEntityRoleAssignment. This function is very easy to use, since it does not have any mandatory parameters. Just connect to the NSX Manager server(s) and run the function.
Get-NsxEntityRoleAssignment | Format-Table -AutoSize
Get-NsxEntityRoleAssignment | Export-Csv -Notype .\NsxUsersAndDomains.csv


  • The function has three optional parameters, which in general are filters for various kinds of queries. The parameter -Entity only returns users and groups that contain the specified word in their name. The parameter is positional and does not need the * character.
Get-NsxEntityRoleAssignment nsx
Get-NsxEntityRoleAssignment -Entity nsx


  • The parameter -Role allows filtering only those who are assigned a given role.
Get-NsxEntityRoleAssignment -Role 'Security Administrator'
Get-NsxEntityRoleAssignment -Role Auditor


  • The -AccessScope parameter is a flag that will show only the roles defined within any Access Scope, i.e. not global roles.
Get-NsxEntityRoleAssignment -AccessScope


  • Of course you can combine these filters in any order.
Get-NsxEntityRoleAssignment -Entity admin -Role 'Security Administrator'
Get-NsxEntityRoleAssignment -Entity admin -AccessScope


  • And of course, no one forbids you to make your own filters.
Get-NsxEntityRoleAssignment | Where-Object {$_.Domain -ne 'cli' -and !$_.Enabled}
Get-NsxEntityRoleAssignment | Where-Object {$_.Type -eq 'group'}


  • All the functions support simultaneous operation with multiple NSX Managers, but do not allow you to select any of them. All functions are executed on all connected NSX servers. To make sure where you are connected, check the value of the $DefaultNSXConnection variable or use my Set-PowerCLITitle function, for some time it supports NSX servers too.


  • All functions support both adding or removing role assignments for multiple users -User or groups -Group at once.
  • The script contains an internal helper function Get-NsxRoleDisplayName, which translates the role names that you see in the UI into those used in API requests. Note that not all roles supported by the function will be supported by your NSX version, some have been added only starting from a specific version. Use the -Verbose switch when adding roles to receive relevant notifications about this.

Add-NsxEntityRoleAssignment NSXAdmin1@vsphere.local -Verbose
Get-NsxEdge esg_Lab1 | Add-NsxEntityAccessScope NSXAdmin1@vsphere.local -Role 'Network Engineer' -Verbose
  • For more details about any function, please take a look at the content based help and examples.
Get-Help Get-NsxEntityRoleAssignment -Full
Get-Help Add-NsxEntityAccessScope -Examples
Get-Help Remove-NsxEntityRoleAssignment -Online

You might also like

Set-PowerCLiTitle – Connect-VIServer deep dive
Get-Version – Get any VMware object version
Get-VMHostCDP – Leverage Cisco Discovery Protocol
Sort-IpAddress – Intellectually sort IP addresses w/PowerShell

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s