This project is read-only.
Roles, privileges and permissions
The security in virtual infrastructure (VI) is organised around
  • privileges, specific rights on ESX Servers, Virtual Machines, or other VI objects. For example the right to start a Virtual Machine
  • roles, are objects that group specific rights together for easier assignment. The Virtual Machine User role has several rights to intercat with a guest.
  • permissions, is where you combine users, or groups, with specific roles.

To see all the available privileges in VI you can do:

PS C:\> Get-TkeAllPriviliges

Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read
ManageCustomFields                                               False Global                             Global.ManageCustomFields

This advanced function returns an array of AuthorizationPrivilege objects.
See the API Reference guide for an explanation of the properties.

To see the roles that are currently defined in the VI you can do:

PS C:\> Get-TkeRoles


Name      : NoAccess
Label     : No Access
Summary   : Used for restricting granted access
RoleId    : -5
System    : True
Privilege :

Name      : Anonymous
Label     : Anonymous
Summary   : Not logged-in user (cannot be granted)
RoleId    : -4
System    : True
Privilege : {System.Anonymous}

Name      : View
Label     : View
Summary   : Visibility access (cannot be granted)
RoleId    : -3
System    : True
Privilege : {System.Anonymous, System.View}

VI comes with a number of pre-defined roles.
These pre-defined roles all have a negative RoleId number and cannot be changed.

To see the privileges that are grouped under a specific role you could do

PS C:\> Get-TkeRoles | where {$_.Name -eq "ReadOnly"} | select -ExpandProperty Privilege
System.Anonymous
System.Read
System.View

but there is a specific advanced function to do just that
PS C:\> Get-TkeRolePrivileges -name "readonly"

Name                                                          OnParent privGroupName                      privId
----                                                          -------- -------------                      ------
Anonymous                                                        False System                             System.Anonymous
View                                                             False System                             System.View
Read                                                             False System                             System.Read

Note that the names of the roles do not always correspond literaly with the role names you see in the VI Client.

To create a new role with a specific set of privileges you can do

PS C:\> New-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.PowerOn","VirtualMachine.Interact.PowerOff"
110

The advanced function returns the roleId of the new role.

Note that the privilege Ids are case-sensitive !

You can also start from one of the pre-defined roles.
For that it suffices to clone the role.

PS C:\> Clone-TkeRole "VirtualMachineUser" "My Cloned Role"
113

This advanced function will return the roleId of the new role, similar to the New-TkeRole advanced function.

If you want to make changes to the privileges assigned to a user-defined role (remember, the roles with the positive roleId numbers) you can do

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Suspend"


The Set-TkeRol cmdlet has a parameter, called -append, which allows you to specify if the privileges need to be added (-append:$true) to the existing privileges or need to replace (-append:$false) the existing privileges.

PS C:\> Set-TkeRole -name "My new role" -privIds "VirtualMachine.Interact.Reset" -append:$true


You can also change the name of a user-defined role

PS C:\> Set-TkeRole -name "My new role" -newName "A new name for the role"


If a role becomes obsolete, you can remove it like this

PS C:\> Remove-TkeRole -name "A new name for the role"

As a failsafe this cmdlet has a switch, called -FailIfUsed, which prohibits the removal of the role if the role is used in a permission.
The default for this switch is -FailIfUsed:$true.

PS C:\> Remove-TkeRole -name "A new name for the role" -FailIfUsed:$false


Once you have the roles set up like you want, you can start assigning permissions.

A permission can be used on practicaly all of the VI objects.
As a guideline, if the object has a Permissions tab in the VI Client, you assign permissions to it.

To set a permission, use the Set-TkePermissions advanced function.
The -permission parameter accepts one or more (an array) Permission object(s).
See the API Reference guide for an explanation of the properties.

In this example we assign the privileges, defined in the ReadOnly role, to the user account Test\Guest.
The permission will only be applied to the object itself, not to any of it's cildren.

PS C:\> $MyPermission = New-Object VMware.Vim.Permission
PS C:\> $MyPermission.principal = "Test\Guest"
PS C:\> $MyPermission.group = $false
PS C:\> $myPermission.propagate = $false
PS C:\> $MyPermission.RoleId = (Get-TkeRoles | Where-Object {$_.Name -eq "ReadOnly"} | % {$_.RoleId})
PS C:\> Get-VM PC2 | Set-TkePermissions -permission $myPermission
PS C:\> Get-VM PC2 | Get-TkePermissions

Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly

The example also showed the use of the Get-TkePermissions cmdlet.
This will list all permissions that are set on a VI object.

If you also want to see the permissions that were inherited for that object, you need to use the -inherited parameter.

PS C:\> Get-VM PC2 | Get-TkePermissions -inherited:$true


Entity    : PC2
Group     : False
Principal : TEST\Guest
Propagate : False
Role      : ReadOnly

Entity    : Datacenters
Group     : True
Principal : TEST\Domain Admins
Propagate : True
Role      : Admin

The removal of a permission is rather straight-forward.

PS C:\> Get-VM PC2 | Remove-TkePermissions -principal "Test\Guest"

Last edited Jan 1, 2009 at 10:40 AM by LucD, version 1

Comments

No comments yet.