exit when child finish
[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
67privileges:
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
112role:
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
128permission:
129
130 Assign roles to users or groups.
131
132
133ACL and Objects:
134================
135
136An 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
138Object: A Virtual machine, Network (bridge, venet), Hosts, Host Memory, Storage, ...
139
140We 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
142There is at most one object permission per user or group
143
144We 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
151User Database:
152
153To keep it simple, we suggest to use a single text file, which is replicated to all cluster nodes.
154
155Also, we can store ACLs inside this file.
156
157Here is a short example how such file could look like:
158
159-----User/Group/Role Database example--------
160
161user:joe@example.com:$1$nd91DtDy$mJtzWJAN2AAABKij0JgMy1/:Joe Average:Just a comment:
162user:max@example.com:$1$nd91DtDy$LANSNJAN2AAABKidhfgMy3/:Max Mustermann:Another comment:
163user:edward@example.com:$1$nd91DtDy$LANSNAAAAAAABKidhfgMy3/:Edward Example:Example VM Manager:
164
165group:admin:Internal Administrator Group:root:
166group:audit:Read only accounts used for audit::
167group:customers:Our Customers:joe@example.com,max@example.com:
168
169role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
170role:vm_manager:Virtual Machine Manager:VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
171role:vm_operator:Virtual Machine Operator:VM.Create,VM.ConfigureCD,VM.Console,VM.AddNewDisk,VM.PowerOn,VM.PowerOff:
172role:ds_consumer:DataStore Consumer:Datastore.AllocateSpace:
173role:nw_consumer:Network Consumer:Network.AssignNetwork:
174
175# group admin can do anything
176acl:0:/:@admin:Administrator:
177# group audit can view anything
178acl:1:/:@audit:read_only:
179
180# user max can manage all qemu/kvm machines
181acl:1:/vm/qemu:max@example.com:vm_manager:
182
183# user joe can use openvz vm 230
184acl:1:/vm/openvz/230:joe@example.com:vm_user:
185
186# user Edward can create openvz VMs using vmbr0 and store0
187acl:1:/vm/openvz:edward@example.com:vm_operator:
188acl:1:/network/vmbr0:edward@example.com:ds_consumer:
189acl:1:/storage/store0:edward@example.com:nw_consumer:
190
191---------------------------------------------
192
193Basic model RBAC -> http://en.wikipedia.org/wiki/Role-based_access_control
194
195# Subject: A person or automated agent
196subject:joe@example.com:
197subject:max@example.com:
198
199# Role: Job function or title which defines an authority level
200role:vm_user:Virtual Machine User:
201role:admin:Administrator:
202
203# Subject Assignment: Subject -> Role(s)
204SA:vm_user:joe@example.com,max@example.com:
205SA: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)
209perm:vm_user:VM.ConfigureCD,VM.Console:
210perm:admin:VM.ConfigureCD,VM.Console,VM.Create:
211
212---------------------------------------------
213
214We can merge 'perm' into the 'role' table, because it is
215a 1 -> 1 mapping
216
217subject:joe@example.com:
218subject:max@example.com:
219
220role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
221role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
222
223SA:vm_user:joe@example.com,max@example.com:
224SA:admin:joe@example.com:
225
226-----------------------------------------------
227
228We can have different subject assignment for different objects.
229
230subject:joe@example.com:
231subject:max@example.com:
232
233role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
234role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
235
236# joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
237SA:/vm/openvz:admin:joe@example.com:
238SA:/vm/qemu:vm_user:joe@example.com,max@example.com:
239
240-----------------------------------------------
241
242Let us use more convenient names.
243Use 'user' instead of 'subject'.
244Use 'acl' instead of 'SA'.
245
246user:joe@example.com:
247user:max@example.com:
248
249role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
250role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
251
252# joe is 'admin' for openvz VMs, but 'vm_user' for qemu VMs
253acl:/vm/openvz:admin:joe@example.com:
254acl:/vm/qemu:vm_user:joe@example.com,max@example.com:
255
256-----------------------------------------------
257
258Finally introduce groups to group users. ACL can then
259use 'users' or 'groups'.
260
261user:joe@example.com:
262user:max@example.com:
263
264group:customers:Our Customers:joe@example.com,max@example.com:
265
266role:vm_user:Virtual Machine User:VM.ConfigureCD,VM.Console:
267role:admin:Administrator:VM.ConfigureCD,VM.Console,VM.Create:
268
269acl:/vm/openvz:admin:joe@example.com:
270acl:/vm/qemu:vm_user:@customers:
271
272
273-----------------------------------------------