bump version to 7.1-8
[pve-access-control.git] / 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 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 priviledges
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. The list specifies who or what is allowed to access the object and what operations are allowed to be performed on the object.
158
159 Object: A Virtual machine, Network (bridge, venet), Hosts, Host Memory, Storage, ...
160
161 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.
162
163 There is at most one object permission per user or group
164
165 We store the following attributes for ACLs:
166
167 propagate: propagate permissions down in the hierarchy
168 path: path to uniquely identify the object
169 user_or_group: ID of user or group (group ID start with @)
170 role: list of role IDs.
171
172 User Database:
173
174 To keep it simple, we suggest to use a single text file, which is replicated to all cluster nodes.
175
176 Also, we can store ACLs inside this file.
177
178 Here is a short example how such file could look like:
179
180 -----User/Group/Role Database example--------
181
182 user:joe@example.com:$1$nd91DtDy$mJtzWJAN2AAABKij0JgMy1/:Joe Average:Just a comment:
183 user:max@example.com:$1$nd91DtDy$LANSNJAN2AAABKidhfgMy3/:Max Mustermann:Another comment:
184 user:edward@example.com:$1$nd91DtDy$LANSNAAAAAAABKidhfgMy3/:Edward Example:Example VM Manager:
185
186 group:admin:Internal Administrator Group:root:
187 group:audit:Read only accounts used for audit::
188 group:customers:Our Customers:joe@example.com,max@example.com:
189
190 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
191 role:vm_manager:Virtual Machine Manager:VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
192 role:vm_operator:Virtual Machine Operator:VM.Create,VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
193 role:ds_consumer:DataStore Consumer:Datastore.AllocateSpace:
194 role:nw_consumer:Network Consumer:Network.AssignNetwork:
195
196 # group admin can do anything
197 acl:0:/:@admin:Administrator:
198 # group audit can view anything
199 acl:1:/:@audit:read_only:
200
201 # user max can manage all qemu/kvm machines
202 acl:1:/vm/qemu:max@example.com:vm_manager:
203
204 # user joe can use openvz vm 230
205 acl:1:/vm/openvz/230:joe@example.com:vm_user:
206
207 # user Edward can create openvz VMs using vmbr0 and store0
208 acl:1:/vm/openvz:edward@example.com:vm_operator:
209 acl:1:/network/vmbr0:edward@example.com:ds_consumer:
210 acl:1:/storage/store0:edward@example.com:nw_consumer:
211
212 ---------------------------------------------
213
214 Basic model RBAC -> http://en.wikipedia.org/wiki/Role-based_access_control
215
216 # Subject: A person or automated agent
217 subject:joe@example.com:
218 subject:max@example.com:
219
220 # Role: Job function or title which defines an authority level
221 role:vm_user:Virtual Machine User:
222 role:admin:Administrator:
223
224 # Subject Assignment: Subject -> Role(s)
225 SA:vm_user:joe@example.com,max@example.com:
226 SA:admin:joe@example.com:
227
228 # Permissions: An approval of a mode of access to a resource
229 # Permission Assignment: Role -> Permissions (set of allowed operation)
230 perm:vm_user:VM.ConfigureCD,VM.Console:
231 perm:admin:VM.ConfigureCD,VM.Console,VM.Create:
232
233 ---------------------------------------------
234
235 We can merge 'perm' into the 'role' table, because it is
236 a 1 -> 1 mapping
237
238 subject:joe@example.com:
239 subject:max@example.com:
240
241 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
242 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
243
244 SA:vm_user:joe@example.com,max@example.com:
245 SA:admin:joe@example.com:
246
247 -----------------------------------------------
248
249 We can have different subject assignment for different objects.
250
251 subject:joe@example.com:
252 subject:max@example.com:
253
254 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
255 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
256
257 # joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
258 SA:/vm/openvz:admin:joe@example.com:
259 SA:/vm/qemu:vm_user:joe@example.com,max@example.com:
260
261 -----------------------------------------------
262
263 Let us use more convenient names.
264 Use 'user' instead of 'subject'.
265 Use 'acl' instead of 'SA'.
266
267 user:joe@example.com:
268 user:max@example.com:
269
270 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
271 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
272
273 # joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
274 acl:/vm/openvz:admin:joe@example.com:
275 acl:/vm/qemu:vm_user:joe@example.com,max@example.com:
276
277 -----------------------------------------------
278
279 Finally introduce groups to group users. ACL can then
280 use 'users' or 'groups'.
281
282 user:joe@example.com:
283 user:max@example.com:
284
285 group:customers:Our Customers:joe@example.com,max@example.com:
286
287 role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
288 role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
289
290 acl:/vm/openvz:admin:joe@example.com:
291 acl:/vm/qemu:vm_user:@customers:
292
293
294 -----------------------------------------------