Managing vSphere Global Permissions with PowerShell

Introduction

It appears that working with vSphere global permissions in PowerCLI is not yet possible. It is also my understanding that there is not currently a public API available in vCenter which allows you to manipulate global permissions either. However, thanks to William Lam’s awesome blog post from 2017, I learned that it is possible to add/remove global permissions via the Managed Object Browser (MOB). What’s more, William provides two example PowerShell functions showing how to trigger the required MOB methods using standard Invoke-WebRequest calls. This is great, but unfortunately he only covered adding and removing permissions and I really needed to be able to list the current global permissions on a vCenter server for auditing purposes. So, I got to work and created a new PowerShell module named VIPerms. This module combines the add/remove examples from William’s post with a new function to list all global permissions. In this post I will demonstrate how to install and use this module.

Installation

As with most PowerShell modules VIPerms is available to install via the PowerShell Gallery.

Install-Module -Name "VIPerms" -Scope "CurrentUser"

Once installed you can import the module into your session.

Import-Module -Name "VIPerms"

Connecting to a vCenter Server

The first step is to connect to your vCenter server.

Connect-VIMobServer -Server "vcenter.example.com"

This will prompt for credentials. You will need to use the administrator@vsphere.local account in order to access and manage the global permissions.

If you use self-signed certificates in your environment you will need to skip certificate checking.

Connect-VIMobServer -Server "vcenter.example.com" -SkipCertificateCheck

Listing Global Permissions

To list all global permissions for your vCenter server use the Get-VIGlobalPermission function.

Get-VIGlobalPermission

Principal                                                            PrincipalType Role            Propagate
---------                                                            ------------- ----            ---------
VSPHERE.LOCAL\vpxd-extension-b2df90b0-1e03-11e6-b844-005056bf2aaa    User          Admin           true
VSPHERE.LOCAL\vpxd-b2df90b0-1e03-11e6-b844-005056bf2aaa              User          Admin           true
VSPHERE.LOCAL\vsphere-webclient-b2df90b0-1e03-11e6-b844-005056bf2aaa User          Admin           true
VSPHERE.LOCAL\Administrators                                         Group         Admin           true
VSPHERE.LOCAL\Administrator                                          User          Admin           true
...

Creating Global Permissions

The New-VIGlobalPermission function will allow you to create a global permission. You must supply a user/group name and the identifier of the required role to assign.

First use the Get-VIMobRole function to get the identifier for the specific role.

Get-VIMobRole

Name     Description Id
----     ----------- --
Admin    Admin       -1
ReadOnly ReadOnly    -2
View     View        -3
...

Then use the New-VIGlobalPermission function to create the permission. For example to assign the Admin role to the vSphere user VSPHERE.LOCAL\test-user you would use.

New-VIGlobalPermission -Name "VSPHERE.LOCAL\test-user" -RoleId -1

If you are assigning a role to a group you will need to use the -IsGroup parameter.

New-VIGlobalPermission -Name "VSPHERE.LOCAL\group-of-users" -IsGroup -RoleId -1

By default the global permission will propagate to all children objects. If you would like to override this you can use the -Propagate parameter.

New-VIGlobalPermission -Name "VSPHERE.LOCAL\group-of-users" -IsGroup -RoleId -1 -Propagate:$false

NOTE If you are already using the VMware.PowerCLI module you can use the official Get-VIRole CmdLet in place of the Get-VIMobRole function included in VIPerms.

Removing Global Permissions

The Remove-VIGlobalPermission function will allow you to delete a global permission. You only need to specify the user/group with this function.

Remove-VIGlobalPermission -Name "VSPHERE.LOCAL\test-user"

Again, if you are removing a permission from a group you will need to use the -IsGroup parameter.

Remove-VIGlobalPermission -Name "VSPHERE.LOCAL\group-of-users" -IsGroup

Conclusion

This module is something that I have put together pretty quickly as I needed to automate some global permissions tasks. I have tested it against vSphere 6.0, 6.5 and 6.7 lab environements and it seems to work fine with all versions. Hopefully it is useful to some other people out there! If you have any questions or feedback then you can find me on twitter.