ryan-jan / viperms

PowerShell helper module for vSphere permissions.

VIPerms

VIPerms is a PowerShell module to help manage vSphere global permissions. There does not appear to be a public API for managing global permissions currently. However, it is possible to manipulate them using the Managed Object Browser (MOB). This module wraps web requests to the MOB into PowerShell commands.

Getting Started

Installation is simple via the PowerShell Gallery.

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

The first thing you need to do is use the Connect-VIMobServer function to make a connection to your vCenter server. When prompted you must supply the [email protected] credentials.

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

Once you have successfully connected to your vCenter server you can use the Get-VIGlobalPermission function to list all global permissions.

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
...

Add/Remove Global Permissions

New-VIGlobalPermission

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

Remove-VIGlobalPermission

The Remove-VIGlobalPermission function will allow you to delete a global permission.

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

Again, f 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

Self-Signed Certificates

If your environment makes use of self-signed certificates then you will need to use the -SkipCertificateCheck parameter when connecting to your vCenter server. For example:

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

This will also set the $Global:VIPerms.SkipCertificateCheck property to $true to avoid you having to specify the -SkipCertificateCheck parameter on subsequent commands for your current PowerShell session.

Acknowledgements

The idea for this module came from William Lam's GlobalPermissions.ps1 script. This gave me the information I needed to be able to interact with the MOB service via PowerShell.

viperms's Issues

Implement role export and config testing commands

Implement function to be able to export one or more roles (and their permissions lists) to JSON. Also implement command to test the exported configuration against the vCenter role to check for configuration drift from the intended permissions list for the role.

Implement platyPS external documentation.

Move away from comment based PowerShell function help to external xml help files generated by platyPS.

CertificatePolicy obsolete in PowerShell 7.1

Thank you for this useful module.

We have been using it successfully with PowerShell version 5.1, but it appears that the switch -SkipCertificateCheck on the cmdlet Connect-VIMobServer does not work with powershell version 7.1

Searching online I see that ICertificatePolicy and CertificatePolicy are obsolete, https://docs.microsoft.com/en-us/dotnet/api/system.net.servicepointmanager.certificatepolicy?view=netframework-4.7.2

Is there a work around or an alternative way of using this module?

This is the error we get:

    PS /scripts> Import-Module -Name "VIPerms"
    PS /scripts> [securestring]$secStringPassword = ConvertTo-SecureString "*******" -AsPlainText -Force
    PS /scripts> [pscredential]$credObject = New-Object System.Management.Automation.PSCredential ("*****", $secStringPassword)
    PS /scripts> Connect-VIMobServer -Server "10.0.0.10" -Credential $credObject -SkipCertificateCheck
    Add-Type: /home/host/.local/share/powershell/Modules/VIPerms/0.0.6/Private/Set-CertPolicy.ps1:24
    Line |
      24 |                      Add-Type -TypeDefinition  @"
         |                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         | (3,56): error CS0246: The type or namespace name 'ICertificatePolicy' could not be found (are you
         | missing a using directive or an assembly reference?)                     public class
         | TrustAllCertsPolicy : ICertificatePolicy {                                                        ^

    Add-Type: /home/host/.local/share/powershell/Modules/VIPerms/0.0.6/Private/Set-CertPolicy.ps1:24
    Line |
      24 |                      Add-Type -TypeDefinition  @"
          |                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
          | Cannot add type. Compilation errors occurred.

The version of Powershell that fails is 7.1.0

    PS /scripts> $PSVersionTable.PSVersion
    Major  Minor  Patch  PreReleaseLabel BuildLabel
    -----  -----  -----  --------------- ----------
    7      1      0

Implement MKDocs documentation and host on readthedocs

Implement MKDocs documentation. Host on readthedocs.