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 paswords 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
 100         Datastore.Allocate: create/remove/modify a data store.
 101         Datastore.AllocateSpace: allocate space on a datastore
 102         Datastore.AllocateTemplate: allocate/upload templates and iso images
 103         Datastore.Audit: view/browse a datastore
 104
 105         Permissions.Modify: modify access permissions
 106
 107         Sys.PowerMgmt: Node power management (start, stop, reset, shutdown, ...)
 108         Sys.Console: console access to Node
 109         Sys.Syslog: view Syslog
 110         Sys.Audit: view node status/config
 111
 112
 113         We may need to refine those in future - the following privs
 114         are just examples:
 115
 116         VM.Create: create new VM to server inventory
 117         VM.Remove: remove VM from inventory
 118         VM.AddNewDisk: add new disk to VM
 119         VM.AddExistingDisk: add an existing disk to VM
 120         VM.DiskModify: modify disk space for associated VM
 121         VM.UseRawDevice: associate a raw device with VM
 122         VM.PowerOn: power on VM
 123         VM.PowerOff: power off VM
 124         VM.CpuModify: modify number of CPUs associated with VM
 125         VM.CpuCyclesModify: modify CPU cycles for VM
 126         VM.NetworkAdd: add network device to VM
 127         VM.NetworkConfigure: configure network device associated with VM
 128         VM.NetworkRemove: remove network device from VM
 129
 130         Network.AssignNetwork: assign system networks
 131
 132 role:
 133
 134         defines a sets of priviledges
 135
 136         predefined roles:
 137
 138         administrator: full administrative privileges
 139         read_only: read only
 140         no_access: no privileges
 141
 142         We store the following attribute for roles:
 143
 144         role_name: the name of the group
 145         description: a more verbose description
 146         privileges: list of privileges
 147
 148 permission:
 149
 150         Assign roles to users or groups.
 151
 152
 153 ACL and Objects:
 154 ================
 155
 156 An access control list (ACL) is a list of permissions attached to an object. The list specifies who or what is allowed to access the object and what operations are allowed to be performed on the object.
 157
 158 Object: A Virtual machine, Network (bridge, venet), Hosts, Host Memory, Storage, ...
 159
 160 We can identify our objects by an unique (file system like) path, which also defines a tree like hierarchy relation. ACL can be inherited. Permissions are inherited if the propagate flag is set on the parent. Child permissions always overwrite inherited permissions. User permission takes precedence over all group permissions. If multiple group permission apply the resulting role is the union of all those group priviledges.
 161
 162 There is at most one object permission per user or group
 163
 164 We store the following attributes for ACLs:
 165
 166         propagate: propagate permissions down in the hierarchy
 167         path: path to uniquely identify the object
 168         user_or_group: ID of user or group (group ID start with @)
 169         role: list of role IDs.
 170
 171 User Database:
 172
 173 To keep it simple, we suggest to use a single text file, which is replicated to all cluster nodes.
 174
 175 Also, we can store ACLs inside this file.
 176
 177 Here is a short example how such file could look like:
 178
 179 -----User/Group/Role Database example--------
 180
 181 user:joe@example.com:$1$nd91DtDy$mJtzWJAN2AAABKij0JgMy1/:Joe Average:Just a comment:
 182 user:max@example.com:$1$nd91DtDy$LANSNJAN2AAABKidhfgMy3/:Max Mustermann:Another comment:
 183 user:edward@example.com:$1$nd91DtDy$LANSNAAAAAAABKidhfgMy3/:Edward Example:Example VM Manager:
 184
 185 group:admin:Internal Administrator Group:root:
 186 group:audit:Read only accounts used for audit::
 187 group:customers:Our Customers:joe@example.com,max@example.com:
 188
 189 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 190 role:vm_manager:Virtual Machine Manager:VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
 191 role:vm_operator:Virtual Machine Operator:VM.Create,VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
 192 role:ds_consumer:DataStore Consumer:Datastore.AllocateSpace:
 193 role:nw_consumer:Network Consumer:Network.AssignNetwork:
 194
 195 # group admin can do anything
 196 acl:0:/:@admin:Administrator:
 197 # group audit can view anything
 198 acl:1:/:@audit:read_only:
 199
 200 # user max can manage all qemu/kvm machines
 201 acl:1:/vm/qemu:max@example.com:vm_manager:
 202
 203 # user joe can use openvz vm 230
 204 acl:1:/vm/openvz/230:joe@example.com:vm_user:
 205
 206 # user Edward can create openvz VMs using vmbr0 and store0
 207 acl:1:/vm/openvz:edward@example.com:vm_operator:
 208 acl:1:/network/vmbr0:edward@example.com:ds_consumer:
 209 acl:1:/storage/store0:edward@example.com:nw_consumer:
 210
 211 ---------------------------------------------
 212
 213 Basic model RBAC -> http://en.wikipedia.org/wiki/Role-based_access_control
 214
 215 # Subject: A person or automated agent
 216 subject:joe@example.com:
 217 subject:max@example.com:
 218
 219 # Role: Job function or title which defines an authority level
 220 role:vm_user:Virtual Machine User:
 221 role:admin:Administrator:
 222
 223 # Subject Assignment: Subject -> Role(s)
 224 SA:vm_user:joe@example.com,max@example.com:
 225 SA:admin:joe@example.com:
 226
 227 # Permissions: An approval of a mode of access to a resource
 228 # Permission Assignment: Role -> Permissions (set of allowed operation)
 229 perm:vm_user:VM.ConfigureCD,VM.Console:
 230 perm:admin:VM.ConfigureCD,VM.Console,VM.Create:
 231
 232 ---------------------------------------------
 233
 234 We can merge 'perm' into the 'role' table, because it is
 235 a 1 -> 1 mapping
 236
 237 subject:joe@example.com:
 238 subject:max@example.com:
 239
 240 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 241 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 242
 243 SA:vm_user:joe@example.com,max@example.com:
 244 SA:admin:joe@example.com:
 245
 246 -----------------------------------------------
 247
 248 We can have different subject assignment for different objects.
 249
 250 subject:joe@example.com:
 251 subject:max@example.com:
 252
 253 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 254 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 255
 256 # joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
 257 SA:/vm/openvz:admin:joe@example.com:
 258 SA:/vm/qemu:vm_user:joe@example.com,max@example.com:
 259
 260 -----------------------------------------------
 261
 262 Let us use more convenient names.
 263 Use 'user' instead of 'subject'.
 264 Use 'acl' instead of 'SA'.
 265
 266 user:joe@example.com:
 267 user:max@example.com:
 268
 269 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 270 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 271
 272 # joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
 273 acl:/vm/openvz:admin:joe@example.com:
 274 acl:/vm/qemu:vm_user:joe@example.com,max@example.com:
 275
 276 -----------------------------------------------
 277
 278 Finally introduce groups to group users. ACL can then
 279 use 'users' or 'groups'.
 280
 281 user:joe@example.com:
 282 user:max@example.com:
 283
 284 group:customers:Our Customers:joe@example.com,max@example.com:
 285
 286 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
 287 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
 288
 289 acl:/vm/openvz:admin:joe@example.com:
 290 acl:/vm/qemu:vm_user:@customers:
 291
 292
 293 -----------------------------------------------