How To Manage and Audit vSphere Permissions with PowerCLI

I am a huge fan of automation and using scripting tools to do the job much easier than working with a GUI interface. PowerCLI is a great way to automate processes and activities in vSphere. You can use PowerCLI for to manage and audit vSphere permissions, which is a great way to pull these using scripts, etc. In this post, let’s see how we can do this.

What are vSphere Permissions?

What exactly are vSphere Permissions, and what do they allow you to do? They detail what a user can do in the vSphere environment. When you create permissions, these get assigned to roles. You can then assign these to users or groups.

VMware PowerCLI install

To work with permissions, roles, etc, you will need to install VMware.PowerCLI module. It is easy to install with the command:

Install-Module VMware.PowerCLI

We will use this module and associated cmdlets in the rest of the walkthrough below.

Connect to vCenter Server

First let’s connect to vCenter Server.

# Connect to vCenter Server
Connect-VIServer -Server vcenter-server-address -User username -Password password

List roles and vSphere permissions PowerCLI

Let’s list the available roles in vSphere using the cmdlet:

Get-VIRole

PowerCLI provides a command to list all available privileges in vCenter. This can be a helpful command for understanding privileges.

# List all available privileges
Get-VIPrivilege

Checking Specific User Permissions

To check the permissions assigned to a specific user, use:

# Check permissions for a specific user
Get-VIPermission -Principal "User1"

Assigning Privileges to Roles

Assigning privileges to roles is important. You can create a new role and assign specific privileges using PowerCLI. As always you don’t want to assign more privileges than needed. Below, we are assigning the permissions to power on VMs to a new role called “CustomRole“.

# Create a new role with specific privileges 
New-VIRole -Name "CustomRole" -Privilege (Get-VIPrivilege -Id "VirtualMachine.Interact.PowerOn")

Changing Existing Roles

To modify an existing role, adding or removing privileges, use the commands that follow:

# Add a privilege to an existing role
Set-VIRole -Role "CustomRole" -AddPrivilege (Get-VIPrivilege -Id "VirtualMachine.Interact.PowerOff")

# Remove a privilege from an existing role
Set-VIRole -Role "CustomRole" -RemovePrivilege (Get-VIPrivilege -Id "VirtualMachine.Interact.PowerOn")

Assigning and Propagating Permissions

Permissions link roles with users or groups. To create a permission and assign it in your environment:

# Assign a role to a user at a specific level
New-VIPermission -Entity (Get-VM -Name "VM1") -Principal "User1" -Role "CustomRole" -Propagate:$true

When assigning permissions, you will likely want to propagate them to child objects in the environment. Here’s how you do that:

# Assign and propagate permissions to child objects
New-VIPermission -Entity (Get-Cluster -Name "Cluster1") -Principal "User1" -Role "CustomRole" -Propagate:$true

Managing User and Group Permissions

To manage local users, groups, and policies in vSphere using PowerCLI, you need to leverage an open-source module called VMware.vSphere.SsoAdmin. Check out the official VMware blog here: New Open Source PowerCLI Module for managing vCenter Single Sign-On (SSO) – VMware PowerCLI Blog.

By default, if you just install the VMware.PowerCLI module, you can’t manage local SSO users and groups and policies. This SSOAdmin module includes cmdlets to manage Single Sign-On (SSO) users and groups within the vSphere environment.

To install the module, you can use the cmdlet:

Install-Module VMware.vSphere.SsoAdmin

Connecting to the SSOAdmin Server

This module has its own connect command that needs to be used in the form of:

connect-ssoadminserver -server vcsa.cloud.local -user [email protected] -skipcertificatecheck

Creating a new SSO user

With the new module installed, we can create a new user in the SSO domain, using the cmdlet New-SsoPersonUser:

New-SsoPersonUser -User mytestadmin -Password 'MyStrongPa$$w0rd' -EmailAddress '[email protected]' -FirstName 'My' -LastName 'Admin'

Creating a New Group

Also, you can create a new group using the New-SsoGroup cmdlet:

# Create a new group in the local SSO domain 
New-SsoGroup -Name 'myGroup' -Description 'My Group Description'

Assigning Users to Groups

Once you have created users and groups, you can assign users to groups using the Add-SsoGroupMember cmdlet:

#Get the group details
$administratorsGroup = Get-SsoGroup -Name 'Administrators' -Domain 'vsphere.local'

#Add the user to the group
Get-SsoPersonUser -Name 'TestUser' -Domain 'MyDomain' | Add-UserToSsoGroup -TargetGroup $administratorsGroup

Assigning Roles to Users and Groups

# Assign a role to a user 
Set-VIPermission -Entity (Get-Datacenter -Name "Datacenter1") -Principal "vsphere.local\newuser" -Role "CustomRole" 

# Assign a role to a group 
Set-VIPermission -Entity (Get-Datacenter -Name "Datacenter1") -Principal "vsphere.local\newgroup" -Role "CustomRole"

Roles with PowerCLI

Creating custom roles for your permissions needs:

# Create a new role with specific privileges
New-VIRole -Name "BackupAdmin" -Privilege (Get-VIPrivilege -Id "Datastore.AllocateSpace", "Datastore.Browse")

Deleting Roles

You can also delete roles this way:

# Delete an existing role
Remove-VIRole -Role "BackupAdmin"

Importing and Exporting Permissions

You can export permissions as well for backup, as an example:

# Export permissions to a file
Get-VIPermission | Export-Csv -Path "permissions.csv"

Importing Permissions

To import permissions from a file:

# Import permissions from a file
Import-Csv -Path "permissions.csv" | ForEach-Object {
    New-VIPermission -Entity (Get-View -Id $_.Entity) -Principal $_.Principal -Role $_.Role -Propagate:$_.Propagate
}

Wrapping up

Managing vSphere permissions with PowerCLI offers a powerful way to automate and streamline the process. There are limitations with getting access to SSO users and groups with the built-in functionality in VMware.PowerCLI. So, we need to also install the VMware.vSphere.SSOAdmin module. Using this module, we can create SSO users, groups, and manage memberships, etc. Let me know if you guys have used this module before?