| Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |
Privileges are the basic individual rights required to perform operations. They are statically defined and never change for a single version of a product. Examples of privileges are "Power on a virtual machine" or "Configure a host."
Roles are aggregations of privileges, used for convenience. For user-defined roles, the system-defined privileges, "System.Anonymous", "System.View", and "System.Read" are always present.
Permissions are the actual access-control rules. A permission is defined on a ManagedEntity and specifies the user or group ("principal") to which the rule applies. The role specifies the privileges to apply, and the propagate flag specifies whether or not the rule applies to sub-objects of the managed entity.
A ManagedEntity may have multiple permissions, but may have only one permission per user or group. If, when logging in, a user has both a user permission and a group permission (as a group member) for the same entity, then the user-specific permission takes precedent. If there is no user-specific permission, but two or more group permissions are present, and the user is a member of the groups, then the privileges are the union of the specified roles.
Managed entities may be collected together into a "complex entity" for the purpose of applying permissions consistently. Complex entities may have a Datacenter, ComputeResource, or ClusterComputeResource as a parent, with other child managed objects as additional parts of the complex entity:
In a group of fault-tolerance (FT) protected VirtualMachines, the secondary VirtualMachines are forced to inherit permissions from the primary VirtualMachine. Queries to discover permissions on FT secondary VMs always return the primary VM as the object that defines the permissions. Permissions defined on an FT primary VM are always applicable on its secondary VMs, but can only be defined or modified on the primary VM.
Properties
Name | Type | Description |
---|---|---|
description P | AuthorizationDescription |
Static, descriptive strings for system roles and privileges.
|
privilegeList* P | AuthorizationPrivilege[] |
The list of system-defined privileges.
|
roleList* P | AuthorizationRole[] |
The currently defined roles in the system, including
static system-defined roles.
|
Methods
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
name P | xsd:string |
Name of the new role.
Since 2.0 |
privIds* P | xsd:string[] |
List of privileges to assign to the role.
Since 2.0 |
Return Value
Type | Description |
---|---|
xsd:int | The roleId assigned to the new role. |
Faults
Type | Description |
---|---|
AlreadyExists | Thrown if a role with the given name already exists. |
InvalidName | Thrown if the role name is empty. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
This API is implemented only by vCenter Server.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entities P | ManagedObjectReference[]
to a ManagedEntity[] |
are the entities to retrieve privileges on
Since vSphere API 6.5 |
userName P | xsd:string |
is the user to retrieve privileges for
Since vSphere API 6.5 |
Return Value
Type | Description |
---|---|
UserPrivilegeResult[] | The privilege check result for each entity |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
If the session does not exist, false is returned for all privileges of all the entities.
This API is implemented only by vCenter Server.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entity P | ManagedObjectReference[]
to a ManagedEntity[] |
The set of entities on which the privileges are checked.
Since vSphere API 5.5 |
sessionId P | xsd:string |
The session ID to check privileges for. A sesssion ID can be
obtained from key.
Since vSphere API 5.5 |
privId* P | xsd:string[] |
The array of privilege IDs to check.
Since vSphere API 5.5 |
Return Value
Type | Description |
---|---|
EntityPrivilege[] | The privilege check result. |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
If the session does not exist, false is returned for all privileges.
This API is implemented only by vCenter Server.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entity P | ManagedObjectReference
to a ManagedEntity |
The entity on which the privileges are checked.
Since vSphere API 5.0 |
sessionId P | xsd:string |
The session ID to check privileges for. A sesssion ID can be
obtained from key.
Since vSphere API 5.0 |
privId* P | xsd:string[] |
The array of privilege IDs to check.
Since vSphere API 5.0 |
Return Value
Type | Description |
---|---|
xsd:boolean[] | A boolean value for each privilege indicating whether the session holds the privilege. |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
This API is implemented only by vCenter Server.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entities P | ManagedObjectReference[] |
are the managed objects to check privileges on. If they
refer to managed objects that are not managed entities
the privilege check will be done on the root folder.
Since vSphere API 6.5 |
userName P | xsd:string |
is the name of the user to check privileges for. Both
UPN and PreWindows2000LogonName user name formats
are supported.
Since vSphere API 6.5 |
privId* P | xsd:string[] |
is the set of privileges to check for
Since vSphere API 6.5 |
Return Value
Type | Description |
---|---|
EntityPrivilege[] | The privilege check result |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
srcRoleId P | xsd:int |
The ID of the source role providing the permissions
which are changing.
Since 2.0 |
dstRoleId P | xsd:int |
The ID of the destination role to which the
permissions are reassigned.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
AuthMinimumAdminPermission | Thrown if srcRoleId is the Administrator role, meaning that applying the change would leave the system with no Administrator permission on the root node. |
NotFound | Thrown if either the source or destination role does not exist. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
roleId P | xsd:int |
Since 2.0 |
failIfUsed P | xsd:boolean |
If true, prevents the role from being
removed if any permissions are using it.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
NotFound | Thrown if the role does not exist. |
RemoveFailed | Thrown if failIfUsed is true and the role has permissions. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
This will fail with an InvalidArgument fault if called on: the direct child folders of a datacenter managed object, the root resource pool of a ComputeResource or ClusterComputeResource, or a HostSystem that is part of a ComputeResource (Stand-alone Host). These objects always have the same permissions as their parent.
This will fail with an InvalidArgument fault if called on a fault-tolerance (FT) secondary VirtualMachine. Such a VirtualMachine always has the same permissions as its FT primary VirtualMachine.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entity P | ManagedObjectReference
to a ManagedEntity |
Entity on which a permission is removed.
Since 2.0 |
user P | xsd:string |
User or group for which the permission is defined.
Since 2.0 |
isGroup P | xsd:boolean |
True, if user refers to a group name; false, for a user name.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
AuthMinimumAdminPermission | Thrown if this change would leave the system with no Administrator permission on the root node. |
NotFound | Thrown if a permission for this entity and user or group does not exist. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
If a permission is specified multiple times for the same user or group, the last permission specified takes effect.
The operation is transactional per permission and could partially fail. The updates are performed in the order of the permission array argument. The first failed update will abort the operation and throw the appropriate exception. When the operation aborts, any permissions that have not yet been removed are left in their original state.
After updates are applied, original permissions that are not in the new set are removed. A failure to remove a permission, such as a violation of the minimum administrator permission rule, will abort the operation and could leave remaining original permissions still effective on the entity.
This will fail with an InvalidArgument fault if called on: the direct child folders of a datacenter managed object, the root resource pool of a ComputeResource or ClusterComputeResource, or a HostSystem that is part of a ComputeResource (Stand-alone Host). These objects always have the same permissions as their parent.
This will fail with an InvalidArgument fault if called on a fault-tolerance (FT) secondary VirtualMachine. Such a VirtualMachine always has the same permissions as its FT primary VirtualMachine.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entity P | ManagedObjectReference
to a ManagedEntity |
The entity on which permissions are updated.
Since 2.0 |
permission* P | Permission[] |
The list of Permission objects that define
the new rules for access to the entity and
potentially entities below it. If the list
is empty, all permissions on the entity are removed.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
AuthMinimumAdminPermission | Thrown if this change would leave the system with no Administrator permission on the root node, or it would grant further permission to a user or group who already has Administrator permission on the root node. |
NotFound | Thrown if a permission for this entity and user or group does not exist. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
UserNotFound | Thrown if one of the given users or groups does not exist. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
Return Value
Type | Description |
---|---|
Permission[] |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
For complex entities, the entity reported as defining the permission may be either the parent or a child entity belonging to the complex entity.
The purpose of this method is to discover permissions for administration purposes, not to determine the current permissions. The current user's permissions are found on the EffectiveRole property of the user's ManagedEntity.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entity P | ManagedObjectReference
to a ManagedEntity |
Since 2.0 |
inherited P | xsd:boolean |
Whether or not to include propagating permissions
defined by parent entities.
Since 2.0 |
Return Value
Type | Description |
---|---|
Permission[] |
Faults
Type | Description |
---|---|
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
roleId P | xsd:int |
Since 2.0 |
Return Value
Type | Description |
---|---|
Permission[] |
Faults
Type | Description |
---|---|
NotFound | Thrown if the role does not exist. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
If a permission is specified multiple times for the same user or group, then the last permission specified takes effect.
The operation is applied transactionally per permission and is applied to the entity following the order of the elements in the permission array argument. This means that if a failure occurs, the method terminates at that point in the permission array with an exception, leaving at least one and as many as all permissions unapplied.
This will fail with an InvalidArgument fault if called on: the direct child folders of a datacenter managed object, the root resource pool of a ComputeResource or ClusterComputeResource, or a HostSystem that is part of a ComputeResource (Stand-alone Host). These objects always have the same permissions as their parent.
This will fail with an InvalidArgument fault if called on a fault-tolerance (FT) secondary VirtualMachine. Such a VirtualMachine always has the same permissions as its FT primary VirtualMachine.
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
entity P | ManagedObjectReference
to a ManagedEntity |
The entity on which to set permissions.
Since 2.0 |
permission* P | Permission[] |
An array of specifications for permissions on the entity.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
AuthMinimumAdminPermission | Thrown if this change would leave the system with no Administrator permission on the root node, or it would grant further permission to a user or group who already has Administrator permission on the root node. |
NotFound | Thrown if a permission's roleId is not valid. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
UserNotFound | Thrown if a given user or group does not exist. |
Events
Type | |
---|---|
None |
Parameters
Name | Type | Description |
---|---|---|
_this | ManagedObjectReference | A reference to the AuthorizationManager used to make the method call. |
roleId P | xsd:int |
The ID of the role that is updated.
Since 2.0 |
newName P | xsd:string |
The new name for the role.
Since 2.0 |
privIds* P | xsd:string[] |
The new set of privileges to assign to the role.
Since 2.0 |
Return Value
Type | Description |
---|---|
None |
Faults
Type | Description |
---|---|
AlreadyExists | Thrown if another role with the given name already exists. |
InvalidName | Thrown if the new role name is empty. |
NotFound | Thrown if the role does not exist, or if a privilege in the list cannot be found. |
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error. |
Events
Type | |
---|---|
None |
Top of page | Local Properties | Local Methods | |
Managed Object Types | Data Object Types | All Properties | All Methods |