Managing Roles and Permissions with AuthorizationManager
AuthorizationManager is the service interface for handling permissions and roles assigned to the users and groups you define with HostLocalAccountManager. AuthorizationManager methods allow you to create, modify, and manage roles and permissions, and to obtain information about the roles and permissions defined in the system. If a predefined role does not meet your needs, define a new one that contains only the minimum set of required privileges.
The AuthorizationManager also allows access and prevents access to specific server objects based on the permissions associated with the object.
AuthorizationManager includes methods for managing roles and for managing permissions:
Roles Management. AddAuthorizationRole, RemoveAuthorizationRole, and UpdateAuthorizationRole. See Using Roles to Consolidate Sets of Privileges and Modifying Sample Roles to Create New Roles.
Permissions Management. MergePermissions, RemoveEntityPermission, ResetEntityPermissions, RetrieveAllPermissions, RetrieveEntityPermissions, RetrieveRolePermissions, and SetEntityPermissions. See Granting Privileges Through Permissions.
AuthorizationManager Managed Object shows these methods in a UML diagram for AuthorizationManager and some of its associated data objects.
AuthorizationManager Managed Object
AuthorizationManager properties allow access to information. For example:
The privilegeList property returns a list of all privileges defined on the system, as an array of AuthorizationPrivilege data objects. Privileges are defined by VMware, on the objects and properties contained in the system. These privileges are fixed and cannot be changed by client applications. See Privileges Reference for lists of privileges.
The roleList property returns a list of all currently defined roles, including the system-defined roles, as an array of AuthorizationRole data objects.
Using Roles to Consolidate Sets of Privileges
A role is a named set of one or more privileges. A role is normally defined for a group of people who have common responsibilities in the system, for example, administrators. Each role can have zero to multiple privileges. ESXi defines system roles and user roles.
System roles. Cannot be modified or deleted.
User roles. Apply to different user communities or restrict access for add-on tools. Several predefined user roles are included with vCenter Server and with ESXi systems. You can create new roles using these predefined user roles as a starting point.
System and Sample Roles describes these two types of roles in more detail and lists currently available roles as examples.
System Roles
Superuser access. Encompasses the set of all defined privileges. See Privileges Granted to the Administrator Role for an example list from a vCenter Server system. This role cannot be deleted. By default, the Administrator role is granted to the user or group that owns the root node.
No access. Explicitly denies access to the user or group with this role. Assigning this role to a user account prevents the user from seeing any objects. Use the No Access role to mask subobjects under a higher-level object that has propagated permissions defined.
Read-only access. Encompasses the set of all nonmutable privileges. (System.Anonymous, System.Read, and System.View). Equivalent to a user role with no permissions. Users with this role can read data or properties and call query methods, but cannot make changes to the system.
Visibility access consisting of System.Anonymous and System.View privileges. Cannot be granted.
Sample Roles
Virtual Machine Administrator
Datacenter Administrator
Set of privileges for a virtual machine user that can also make configuration changes and create new virtual machines.
ResourcePool Administrator
VMware Consolidated Backup Utility
Modifying Sample Roles to Create New Roles
The system roles listed in System and Sample Roles cannot be modified or deleted. However, you can create new roles, or modify the sample roles.
To create new roles using the API
1
Starting with the ServiceContent object in ServiceInstance.content, obtain a managed object reference to the AuthorizationManager for the server.
2
Invoke the AddAuthorizationRole method. Parameters are a reference to AuthorizationManager, a name for the role (as a string), and an array of privileges (array of strings) that should be assigned to the role.
AddAuthorizationRole returns an integer (xsd:int) value for the roleId that the system assigns to the newly defined role.
3
In subsequent code, use the roleID to assign the role to specific users or groups.
Granting Privileges Through Permissions
When you use one of the AuthorizationManager objects to assign or modify permissions, you use a Permission data object. Permission associates a principal with a set of privileges. A permission identifies:
The user or group (principal) to which the permission applies.
Every managed entity has at least one Permission object associated with it. A managed entity can have more than one Permission assigned to it, effectively granting different privileges to different users or groups. Permissions are defined for managed entities either explicitly or through inheritance.
Obtaining Information About Permissions
Users with the Administrator role can obtain information about Permission objects at different levels of detail.
For an array of Permission objects, call the AuthorizationManager.RetrieveAllPermissions method.
For a role defined in the system, call the AuthorizationManager.RetrieveRolePermissions method.
See the vSphere API Reference.
Setting, Changing, or Deleting Permissions
The Permission data object associates the privileges required to perform an action on an object with the principals (user, group). Principals have privileges through their role. To set or update permissions on an object, use the AuthorizationManager.SetEntityPermissions method.
To set permissions on an entity
1
Obtain a reference to the AuthorizationManager for the server from the ServiceContent object associated with the ServiceInstance. For example:
ManagedObjectReference hostAuthorizationManager = service.getAuthorizationManager();
2
Create a Permission data object that identifies the user (or group) name, the role, the entity to which the permission should apply, and whether the permission should be applied to the entity’s children.
For example, the following code fragment creates a permission on the root folder of the inventory granting a user Administrator role to the root folder and all its children.
Permission per = new Permission();
per.setGroup(false);
per.setPrincipal(“new_user_name”);
per.setRoleId(-1);
per.setPropagate(true);
per.setEntity(rootFolder);
Permissions cannot be set directly on children in a complex entity. For complex entities, set permissions on the parent entity and set the propagate flag to true to apply permissions to the child entities.
To replace existing permissions with a new set of permissions, use the AuthorizationManager.ResetEntityPermissions method.
Impact of Group Membership on Permissions
Users can be members of multiple groups. The system handles multigroup membership as follows:
Applying Permission to a Managed Entity
Example: Creating a User Account shows some of the code required to create a user account and apply a permission to an entity that grants access to the user account based on a role. The role with role ID 4, assigned in this example, is defined as a “Virtual Machine Power User.” The sample uses AuthorizationManager to grant permissions to the user and to associate the permission with the managed entity in the inventory—in this example, the rootFolder. The example uses the apputil helper classes to access the objects.
Example: Creating a User Account
...
ManagedObjectReference _authManRef = _sic.getAuthorizationManager();
public class CreateUser {
private static AppUtil appUtil= null;
private void createUser() throws Exception {
ManagedObjectReference hostLocalAccountManager = appUtil.getConnection().getServiceContent().getAccountManager();
ManagedObjectReference hostAuthorizationManager =
appUtil.getConnection().getServiceContent().getAuthorizationManager();
 
// Create a user
HostAccountSpec hostAccountSpec = new HostAccountSpec();
hostAccountSpec.setId(userName);
hostAccountSpec.setPassword(password);
hostAccountSpec.setDescription("my delegated admin auto-agent software");
appUtil.getConnection().getService().createUser(hostLocalAccountManager, hostAccountSpec);
ManagedObjectReference rootFolder = appUtil.getConnection().getServiceContent().getRootFolder();
Permission permission = new Permission();
permission.setGroup(false);
permission.setPrincipal(userName);
 
// Assign the Virtual Machine Power User role
permission.setRoleId(4);
permission.setPropagate(true);
permission.setEntity(rootFolder);
appUtil.getConnection().getService().setEntityPermissions(hostAuthorizationManager, rootFolder,
new Permission [] {permission});
...