bump version to 4.0-5
[pve-access-control.git] / README
CommitLineData
2c3a6c0a
DM
1User Management and Access Control
2==================================
3
4Proxmox VE implements an easy but flexible way to manage users. A
5powerful Access Control algorithm is used to grant permissions to
6individual users or group of users.
7
8Best Practices:
9
10Use groups in ACLs (not individual users).
11
12User Authentication
13===================
14
15Proxmox VE can use different authentication servers. Those
16servers are listed in '/etc/pve/priv/domain.cfg', indexed by a unique
17ID (called 'authentication domain' or 'realm').
18
19User names need to be unique. We create unique names by adding the
20'realm' to the user ID: <userid>@<realm>
21
22File format 'domain.cfg'
23----example domains.cfg ------------------
24
25# an active directory server
26AD: mycompany
27 server1 10.10.10.1
28 server2 10.10.10.2
29 ...
30
31# an LDAP server
32LDAP: example.com
33 server1 10.10.10.2
34 ....
35
36------------------------------------------
37
38There 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
45Proposed user database fields:
46==============================
47
48users:
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
61group:
62
63 group_name: the name of the group
64 user_list: list of login names
65 comment: a more verbose description
66
c0fead8c
DM
67pool:
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
2c3a6c0a
DM
74privileges:
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
c0fead8c 83 VM.Monitor: access to VM monitor (kvm)
68d5a86d 84 VM.Backup: backup/restore VMs
7b395f99 85 VM.Clone: Clone VM or VM template
2c3a6c0a 86 VM.Audit: view VM config
c0fead8c
DM
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.
2c3a6c0a
DM
99
100 Datastore.Allocate: create/remove/modify a data store.
101 Datastore.AllocateSpace: allocate space on a datastore
68d5a86d 102 Datastore.AllocateTemplate: allocate/upload templates and iso images
2c3a6c0a
DM
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
2c3a6c0a
DM
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
2c3a6c0a
DM
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
132role:
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
148permission:
149
150 Assign roles to users or groups.
151
152
153ACL and Objects:
154================
155
156An 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
158Object: A Virtual machine, Network (bridge, venet), Hosts, Host Memory, Storage, ...
159
160We 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
162There is at most one object permission per user or group
163
164We 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
171User Database:
172
173To keep it simple, we suggest to use a single text file, which is replicated to all cluster nodes.
174
175Also, we can store ACLs inside this file.
176
177Here is a short example how such file could look like:
178
179-----User/Group/Role Database example--------
180
181user:joe@example.com:$1$nd91DtDy$mJtzWJAN2AAABKij0JgMy1/:Joe Average:Just a comment:
182user:max@example.com:$1$nd91DtDy$LANSNJAN2AAABKidhfgMy3/:Max Mustermann:Another comment:
183user:edward@example.com:$1$nd91DtDy$LANSNAAAAAAABKidhfgMy3/:Edward Example:Example VM Manager:
184
185group:admin:Internal Administrator Group:root:
186group:audit:Read only accounts used for audit::
187group:customers:Our Customers:joe@example.com,max@example.com:
188
189role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
190role:vm_manager:Virtual Machine Manager:VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
191role:vm_operator:Virtual Machine Operator:VM.Create,VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
192role:ds_consumer:DataStore Consumer:Datastore.AllocateSpace:
193role:nw_consumer:Network Consumer:Network.AssignNetwork:
194
195# group admin can do anything
196acl:0:/:@admin:Administrator:
197# group audit can view anything
198acl:1:/:@audit:read_only:
199
200# user max can manage all qemu/kvm machines
201acl:1:/vm/qemu:max@example.com:vm_manager:
202
203# user joe can use openvz vm 230
204acl:1:/vm/openvz/230:joe@example.com:vm_user:
205
206# user Edward can create openvz VMs using vmbr0 and store0
207acl:1:/vm/openvz:edward@example.com:vm_operator:
208acl:1:/network/vmbr0:edward@example.com:ds_consumer:
209acl:1:/storage/store0:edward@example.com:nw_consumer:
210
211---------------------------------------------
212
213Basic model RBAC -> http://en.wikipedia.org/wiki/Role-based_access_control
214
215# Subject: A person or automated agent
216subject:joe@example.com:
217subject:max@example.com:
218
219# Role: Job function or title which defines an authority level
220role:vm_user:Virtual Machine User:
221role:admin:Administrator:
222
223# Subject Assignment: Subject -> Role(s)
224SA:vm_user:joe@example.com,max@example.com:
225SA: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)
229perm:vm_user:VM.ConfigureCD,VM.Console:
230perm:admin:VM.ConfigureCD,VM.Console,VM.Create:
231
232---------------------------------------------
233
234We can merge 'perm' into the 'role' table, because it is
235a 1 -> 1 mapping
236
237subject:joe@example.com:
238subject:max@example.com:
239
240role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
241role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
242
243SA:vm_user:joe@example.com,max@example.com:
244SA:admin:joe@example.com:
245
246-----------------------------------------------
247
248We can have different subject assignment for different objects.
249
250subject:joe@example.com:
251subject:max@example.com:
252
253role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
254role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
255
256# joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
257SA:/vm/openvz:admin:joe@example.com:
258SA:/vm/qemu:vm_user:joe@example.com,max@example.com:
259
260-----------------------------------------------
261
262Let us use more convenient names.
263Use 'user' instead of 'subject'.
264Use 'acl' instead of 'SA'.
265
266user:joe@example.com:
267user:max@example.com:
268
269role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
270role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
271
272# joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
273acl:/vm/openvz:admin:joe@example.com:
274acl:/vm/qemu:vm_user:joe@example.com,max@example.com:
275
276-----------------------------------------------
277
278Finally introduce groups to group users. ACL can then
279use 'users' or 'groups'.
280
281user:joe@example.com:
282user:max@example.com:
283
284group:customers:Our Customers:joe@example.com,max@example.com:
285
286role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
287role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
288
289acl:/vm/openvz:admin:joe@example.com:
290acl:/vm/qemu:vm_user:@customers:
291
292
293-----------------------------------------------