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" } |
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
