README

   1 User Management and Access Control
   2 ==================================
   3
   4 Proxmox VE implements an easy but flexible way to manage users. A
   5 powerful Access Control algorithm is used to grant permissions to
   6 individual users or group of users.
   7
   8 Best Practices:
   9
  10 Use groups in ACLs (not individual users).
  11
  12 User Authentication
  13 ===================
  14
  15 Proxmox VE can use different authentication servers. Those
  16 servers are listed in '/etc/pve/priv/domain.cfg', indexed by a unique
  17 ID (called 'authentication domain' or 'realm').
  18
  19 User names need to be unique. We create unique names by adding the
  20 'realm' to the user ID: <userid>@<realm>
  21
  22 File format 'domain.cfg'
  23 ----example domains.cfg ------------------
  24
  25 # an active directory server
  26 AD: mycompany
  27         server1 10.10.10.1
  28         server2 10.10.10.2
  29         ...
  30
  31 # an LDAP server
  32 LDAP: example.com
  33         server1 10.10.10.2
  34         ....
  35
  36 ------------------------------------------
  37
  38 There are 2 special authentication domains name 'pve' and 'pam':
  39
  40  * pve: stores passwords to "/etc/pve/priv/shadow.cfg" (SHA256 crypt);
  41
  42  * pam: use unix 'pam'
  43
  44
  45 Proposed user database fields:
  46 ==============================
  47
  48 users:
  49
  50         login_name: email address (user@domain)
  51         enable: 1 = TRUE, 0 = FALSE
  52         expire: <integer> (account expiration date)
  53         domid: reference to authentication domain
  54         firstname: user first name
  55         lastname: user last name
  56         email: user's email address
  57         comment: arbitrary comment
  58
  59         special user root: The root user has full administrative privileges
  60
  61 group:
  62
  63         group_name: the name of the group
  64         user_list: list of login names
  65         comment: a more verbose description
  66
  67 pool:
  68
  69         pool_name: the name of the pool
  70         comment: a more verbose description
  71         vm_list: list of VMs associated with the pool
  72         storage_list: list of storage IDs associated with the pool
  73
  74 privileges:
  75
  76         defines rights required to execute actions or read
  77         information.
  78
  79         VM.Allocate: create/remove new VM to server inventory
  80         VM.Migrate: migrate VM to alternate server on cluster
  81         VM.PowerMgmt: power management (start, stop, reset, shutdown, ...)
  82         VM.Console: console access to VM
  83         VM.Monitor: access to VM monitor (kvm)
  84         VM.Backup: backup/restore VMs
  85         VM.Clone: Clone VM or VM template
  86         VM.Audit: view VM config
  87
  88         VM.Config.XXX: modify VM config
  89
  90           VM.Config.Disk: add/modify/delete Disks
  91           VM.Config.CDROM: eject/change CDROM
  92           VM.Config.CPU: modify CPU settings
  93           VM.Config.Memory: modify Memory settings
  94           VM.Config.Network: add/modify/delete Network devices
  95           VM.Config.HWType: modify emulated HW type
  96           VM.Config.Options: modify any other VM configuration
  97
  98         Pool.Allocate: create/remove/modify a pool.
  99         Pool.Audit: view a pool
 100
 101         Datastore.Allocate: create/remove/modify a data store.
 102         Datastore.AllocateSpace: allocate space on a datastore
 103         Datastore.AllocateTemplate: allocate/upload templates and iso images
 104         Datastore.Audit: view/browse a datastore
 105
 106         Permissions.Modify: modify access permissions
 107
 108         Sys.PowerMgmt: Node power management (start, stop, reset, shutdown, ...)
 109         Sys.Console: console access to Node
 110         Sys.Syslog: view Syslog
 111         Sys.Audit: view node status/config
 112
 113
 114         We may need to refine those in future - the following privs
 115         are just examples:
 116
 117         VM.Create: create new VM to server inventory
 118         VM.Remove: remove VM from inventory
 119         VM.AddNewDisk: add new disk to VM
 120         VM.AddExistingDisk: add an existing disk to VM
 121         VM.DiskModify: modify disk space for associated VM
 122         VM.UseRawDevice: associate a raw device with VM
 123         VM.PowerOn: power on VM
 124         VM.PowerOff: power off VM
 125         VM.CpuModify: modify number of CPUs associated with VM
 126         VM.CpuCyclesModify: modify CPU cycles for VM
 127         VM.NetworkAdd: add network device to VM
 128         VM.NetworkConfigure: configure network device associated with VM
 129         VM.NetworkRemove: remove network device from VM
 130
 131         Network.AssignNetwork: assign system networks
 132
 133 role:
 134
 135         defines a sets of privileges
 136
 137         predefined roles:
 138
 139         administrator: full administrative privileges
 140         read_only: read only
 141         no_access: no privileges
 142
 143         We store the following attribute for roles:
 144
 145         role_name: the name of the group
 146         description: a more verbose description
 147         privileges: list of privileges
 148
 149 permission:
 150
 151         Assign roles to users or groups.
 152
 153
 154 ACL and Objects:
 155 ================
 156
 157 An access control list (ACL) is a list of permissions attached to an object.
 158 The list specifies who or what is allowed to access the object and what
 159 operations are allowed to be performed on the object.
 160
 161 Object: A Virtual machine, Network (bridge, venet), Hosts, Host Memory,
 162 Storage, ...
 163
 164 We can identify our objects by an unique (file system like) path, which also
 165 defines a tree like hierarchy relation. ACL can be inherited. Permissions are
 166 inherited if the propagate flag is set on the parent. Child permissions always
 167 overwrite inherited permissions. User permission takes precedence over all
 168 group permissions. If multiple group permission apply the resulting role is the
 169 union of all those group privileges.
 170
 171 There is at most one object permission per user or group
 172
 173 We store the following attributes for ACLs:
 174
 175         propagate: propagate permissions down in the hierarchy
 176         path: path to uniquely identify the object
 177         user_or_group: ID of user or group (group ID start with @)
 178         role: list of role IDs.
 179
 180 User Database:
 181
 182 To keep it simple, we suggest to use a single text file, which is replicated to all cluster nodes.
 183
 184 Also, we can store ACLs inside this file.
 185
 186 Here is a short example how such file could look like:
 187
 188 -----User/Group/Role Database example--------
 189
 190 user:joe@example.com:$1$nd91DtDy$mJtzWJAN2AAABKij0JgMy1/:Joe Average:Just a comment:
 191 user:max@example.com:$1$nd91DtDy$LANSNJAN2AAABKidhfgMy3/:Max Mustermann:Another comment:
 192 user:edward@example.com:$1$nd91DtDy$LANSNAAAAAAABKidhfgMy3/:Edward Example:Example VM Manager:
 193
 194 group:admin:Internal Administrator Group:root:
 195 group:audit:Read only accounts used for audit::
 196 group:customers:Our Customers:joe@example.com,max@example.com:
 197
 198 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 199 role:vm_manager:Virtual Machine Manager:VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
 200 role:vm_operator:Virtual Machine Operator:VM.Create,VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
 201 role:ds_consumer:DataStore Consumer:Datastore.AllocateSpace:
 202 role:nw_consumer:Network Consumer:Network.AssignNetwork:
 203
 204 # group admin can do anything
 205 acl:0:/:@admin:Administrator:
 206 # group audit can view anything
 207 acl:1:/:@audit:read_only:
 208
 209 # user max can manage all qemu/kvm machines
 210 acl:1:/vm/qemu:max@example.com:vm_manager:
 211
 212 # user joe can use openvz vm 230
 213 acl:1:/vm/openvz/230:joe@example.com:vm_user:
 214
 215 # user Edward can create openvz VMs using vmbr0 and store0
 216 acl:1:/vm/openvz:edward@example.com:vm_operator:
 217 acl:1:/network/vmbr0:edward@example.com:ds_consumer:
 218 acl:1:/storage/store0:edward@example.com:nw_consumer:
 219
 220 ---------------------------------------------
 221
 222 Basic model RBAC -> http://en.wikipedia.org/wiki/Role-based_access_control
 223
 224 # Subject: A person or automated agent
 225 subject:joe@example.com:
 226 subject:max@example.com:
 227
 228 # Role: Job function or title which defines an authority level
 229 role:vm_user:Virtual Machine User:
 230 role:admin:Administrator:
 231
 232 # Subject Assignment: Subject -> Role(s)
 233 SA:vm_user:joe@example.com,max@example.com:
 234 SA:admin:joe@example.com:
 235
 236 # Permissions: An approval of a mode of access to a resource
 237 # Permission Assignment: Role -> Permissions (set of allowed operation)
 238 perm:vm_user:VM.ConfigureCD,VM.Console:
 239 perm:admin:VM.ConfigureCD,VM.Console,VM.Create:
 240
 241 ---------------------------------------------
 242
 243 We can merge 'perm' into the 'role' table, because it is
 244 a 1 -> 1 mapping
 245
 246 subject:joe@example.com:
 247 subject:max@example.com:
 248
 249 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 250 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 251
 252 SA:vm_user:joe@example.com,max@example.com:
 253 SA:admin:joe@example.com:
 254
 255 -----------------------------------------------
 256
 257 We can have different subject assignment for different objects.
 258
 259 subject:joe@example.com:
 260 subject:max@example.com:
 261
 262 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 263 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 264
 265 # joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
 266 SA:/vm/openvz:admin:joe@example.com:
 267 SA:/vm/qemu:vm_user:joe@example.com,max@example.com:
 268
 269 -----------------------------------------------
 270
 271 Let us use more convenient names.
 272 Use 'user' instead of 'subject'.
 273 Use 'acl' instead of 'SA'.
 274
 275 user:joe@example.com:
 276 user:max@example.com:
 277
 278 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 279 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 280
 281 # joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
 282 acl:/vm/openvz:admin:joe@example.com:
 283 acl:/vm/qemu:vm_user:joe@example.com,max@example.com:
 284
 285 -----------------------------------------------
 286
 287 Finally introduce groups to group users. ACL can then
 288 use 'users' or 'groups'.
 289
 290 user:joe@example.com:
 291 user:max@example.com:
 292
 293 group:customers:Our Customers:joe@example.com,max@example.com:
 294
 295 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 296 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 297
 298 acl:/vm/openvz:admin:joe@example.com:
 299 acl:/vm/qemu:vm_user:@customers:
 300
 301
 302 -----------------------------------------------