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