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