a2ec7f1ba9117a91fa55be735064bbfc0c62ec71
[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 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 -----------------------------------------------