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