In a vSphere environment, authorization determines what actions an authenticated user is allowed to perform. Once a user is authenticated (i.e., their identity is verified), vSphere enforces access control through a combination of Privileges, Roles, and Permissions. Let’s break these down.
Understanding vSphere Authorization Constructs
Privileges
A Privilege is the most granular unit of access control. Each privilege corresponds to a specific action that a user can perform.
Examples:
- VirtualMachine > Interaction > Power On
- Content Library > Upload a file
Roles
A Role is a collection of one or more privileges. Roles are used to define the capabilities required for a user or group to carry out their tasks.
Examples:
- Read-Only: Grants view-only access.
- Administrator: Grants full access.
- Custom Roles: Created by administrators to tailor specific privilege sets for specific needs.
Permissions
A Permission links a user (or group) to a role on a specific vSphere object. This binding determines who can do what, and where.
Example:
Assign the Power User role to user ‘holodeck-vmadmin’ on the datacenter object.
Why Automate Authorization?
Historically, vSphere administrators lacked native API support for managing roles, privileges, and permissions. This meant that access control operations had to be performed manually—a process prone to human error, inconsistencies, and operational overhead, especially in large-scale environments. With VMware Cloud Foundation (VCF) 9.0, a new set of Global Authorization APIs is now available. These APIs enable full lifecycle management of:
Global Authorization APIs
| Category | Description |
| Privileges | Retrieve and query vCenter authorization privileges |
| Roles | Create, update, delete, and list authorization roles |
| Permissions | Create, update, delete, and list authorization permissions |
Refer to the API documentation for full details.
API Usage Example: Creating a Custom Role
Objective
Create a new role called “Holodeck-VMAdmin” with the ability to perform a set of virtual machine operations.
Required Privileges
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
VirtualMachine.Interact.PowerOff VirtualMachine.Interact.PowerOn VirtualMachine.Interact.Pause VirtualMachine.Interact.Reset VirtualMachine.Interact.SetCDMedia VirtualMachine.Interact.Suspend VirtualMachine.Interact.SuspendToMemory VirtualMachine.Interact.ToolsInstall VirtualMachine.Inventory.Create VirtualMachine.Inventory.CreateFromExisting VirtualMachine.Inventory.Delete VirtualMachine.Inventory.Register VirtualMachine.Inventory.Unregister |
Using Postman
Step 1: Import OpenAPI Spec
- Download the VCF OpenAPI specification.
- Extract the zip and locate:
vcf-api-specs-9.0.0.0-24798170/specifications/vsphere/openapi/automation/vcenter.yaml - Set your vCenter base URL inside servers > url.
servers:
– url: https://your-vc-fqdn-or-ip/api
- Import vcenter.yaml into Postman.
Step 2: Authenticate and Create a Session
- Use the API: POST /api/session
- Provide your credentials in the body.
- Copy the token for subsequent requests.
Step 3: Create Role via API
Endpoint: POST /api/vcenter/authorization/roles
Request Body:
|
1 2 3 4 5 6 7 8 9 |
{ "description": "Holodeck VM Admins", "name": "Holodeck-VM-Admins", "privileges":[ "VirtualMachine.Interact.PowerOff", ... "VirtualMachine.Inventory.Unregister" ] } |
Step 4: Assign Permission
Endpoint: POST /api/vcenter/authorization/permissions
Request Body:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
{ "object": { "id": "datacenter-3", "type": "datacenter" }, "principal": { "name": "holodeck-vmadmin", "type": "USER", "domain": "vsphere.local" }, "propagating": true, "role": "1055868654" } |
The goal of Permissions API is to allow granting both global and inventory permissions for any object with DynamicID that supports it.
To assign an inventory permission, you need to provide the correct DynamicID for the target inventory object. A DynamicID consists of two fields: "type" and "id".
For inventory objects:
- The
"type"field can either be"ManagedEntity"—which applies broadly to all inventory objects like virtual machines, hosts, etc.—or a more specific type depending on the object. - The supported specific types include:
ClusterComputeResource
ComputeResource
Datacenter
Datastore
DistributedVirtualSwitch
DistributedVirtualPortgroup
Folder
HostSystem
Network
OpaqueNetwork
ResourcePool
StoragePod
VirtualApp
VirtualMachine
The "id" field should be set to the Managed Object ID (moID) of the inventory object.
To create a global permission, you also need to provide a DynamicID. However, unlike inventory permissions—where the values of "type" and "id" vary—global permissions always use the same values:
"type":"GlobalAcl""id":"GlobalAcl"
Using VCF PowerCLI SDK
Currently PowerCLI offers the auto generated cmdlets from PowerCLI SDK module. Please check out the detailed blog post on how to use PowerCLI SDK. Below is the sample code to create a role and permission using PowerCLI SDK.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# Create Role Specification $roleSpec = Initialize-VcenterAuthorizationRolesCreateSpec -Name "HoloDeck-VMAdmin" -Description "Only VM operations allowed" -Privileges @("VirtualMachine.Interact.PowerOn", ...) # Create Role $roleId = Invoke-VcenterAuthorizationRolesCreate -VcenterAuthorizationRolesCreateSpec $roleSpec # Create Permission Spec $DynamicID = Initialize-VapiStdDynamicID -Type "datacenter" -Id "datacenter-3" $Principal = Initialize-VcenterAuthorizationPermissionsPrincipal -Type "USER" -Name "holodeck-vmadmin" -Domain "vsphere.local" $PerMissionSpec = Initialize-VcenterAuthorizationPermissionsCreateSpec -Object $DynamicID -Principal $Principal -Role $roleId -Propagating $true # Assign Permission Invoke-VcenterAuthorizationPermissionsCreate -VcenterAuthorizationPermissionsCreateSpec $PerMissionSpec |
Using VCF Python SDK
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
from com.vmware.vapi.std_client import DynamicID from com.vmware.vcenter.authorization_client import Roles, Permissions from vmware.vapi.vsphere.client import create_vsphere_client import requests, urllib3 session = requests.session() session.verify = False urllib3.disable_warnings() client = create_vsphere_client(server='vc-mgmt-a.site-a.vcf.lab', username='administrator@vsphere.local', password='VMware123!', session=session) # Create Role role_spec = Roles.CreateSpec(name="HolodeckVMAdmin", description="VM-only role", privileges={...}) role_id = client.vcenter.authorization.Roles.create(role_spec) # Assign Permission dc = client.vcenter.Datacenter.list()[0].datacenter dyn_id = DynamicID(type='datacenter', id=dc) principal = Permissions.Principal(type=Permissions.Principal.Type("USER"), name="holouser", domain="vsphere.local") perm_spec = Permissions.CreateSpec(object=dyn_id, principal=principal, role=role_id, propagating=True) client.vcenter.authorization.Permissions.create(perm_spec) |
Using VCF Java SDK
Refer to the VCF SDK Java GitHub samples for complete code examples.
Pro-Tips
- Improve your API learning curve by utilizing OpenAPI specification documentation. By importing OpenAPI specification in postman or similar API client tool you can quickly use the APIs
- Currently, High level cmdlets are not available to provide authorization operation. Use VCF PowerCLI SDK as shown in example. Check out how to use VCF PowerCLI SDK.
- Browse to Global Authorization API Sample with VCF Python SDK and VCF Java SDK.
VCF 9.0’s Global Authorization APIs transform vSphere authorization from a manual, error-prone task into an automated, consistent, and scalable process. These APIs empower you to:
- Automate role and permission.
- Enforce least privilege access across your environment.
- Seamlessly integrate access control into your CI/CD and DevOps workflows.
Leverage the PowerCLI, Python, or Java SDKs to build custom automation, modernizing how you manage authorization within your VMware environments and meeting your specific operational needs.
Learning Resources
Demystifying VCF PowerCLI 9.0 SDK
Introducing a Unified VCF SDK 9.0 for Python and Java
Sample Code – Global Authorization APIs with VCF Python SDK
Sample Code – Global Authorization API with VCF Java SDK
Discover more from VMware Cloud Foundation (VCF) Blog
Subscribe to get the latest posts sent to your email.
