Update TFA documentation
[pve-docs.git] / pveum.adoc
1 [[chapter_user_management]]
2 ifdef::manvolnum[]
3 pveum(1)
4 ========
5 :pve-toplevel:
6
7 NAME
8 ----
9
10 pveum - Proxmox VE User Manager
11
12
13 SYNOPSIS
14 --------
15
16 include::pveum.1-synopsis.adoc[]
17
18
19 DESCRIPTION
20 -----------
21 endif::manvolnum[]
22 ifndef::manvolnum[]
23 User Management
24 ===============
25 :pve-toplevel:
26 endif::manvolnum[]
27
28 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
29
30 Proxmox VE supports multiple authentication sources, e.g. Linux PAM,
31 an integrated Proxmox VE authentication server, LDAP, Microsoft Active
32 Directory.
33
34 By using the role based user- and permission management for all
35 objects (VMs, storages, nodes, etc.) granular access can be defined.
36
37
38 [[pveum_users]]
39 Users
40 -----
41
42 {pve} stores user attributes in `/etc/pve/user.cfg`.
43 Passwords are not stored here, users are instead associated with
44 <<pveum_authentication_realms,authentication realms>> described below.
45 Therefore a user is internally often identified by its name and
46 realm in the form `<userid>@<realm>`.
47
48 Each user entry in this file contains the following information:
49
50 * First name
51 * Last name
52 * E-mail address
53 * Group memberships
54 * An optional Expiration date
55 * A comment or note about this user
56 * Whether this user is enabled or disabled
57 * Optional two factor authentication keys
58
59
60 System administrator
61 ~~~~~~~~~~~~~~~~~~~~
62
63 The system's root user can always log in via the Linux PAM realm and is an
64 unconfined administrator. This user cannot be deleted, but attributes can
65 still be changed and system mails will be sent to the email address
66 assigned to this user.
67
68
69 [[pveum_groups]]
70 Groups
71 ~~~~~~
72
73 Each user can be member of several groups. Groups are the preferred
74 way to organize access permissions. You should always grant permission
75 to groups instead of using individual users. That way you will get a
76 much shorter access control list which is easier to handle.
77
78
79 [[pveum_authentication_realms]]
80 Authentication Realms
81 ---------------------
82
83 As {pve} users are just counterparts for users existing on some external
84 realm, the realms have to be configured in `/etc/pve/domains.cfg`.
85 The following realms (authentication methods) are available:
86
87 Linux PAM standard authentication::
88 In this case a system user has to exist (e.g. created via the `adduser`
89 command) on all nodes the user is allowed to login, and the user
90 authenticates with their usual system password.
91 +
92 [source,bash]
93 ----
94 useradd heinz
95 passwd heinz
96 groupadd watchman
97 usermod -a -G watchman heinz
98 ----
99
100 Proxmox VE authentication server::
101 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
102 Password are encrypted using the SHA-256 hash method.
103 This is the most convenient method for small (or even medium)
104 installations where users do not need access to anything outside of
105 {pve}. In this case users are fully managed by {pve} and are able to
106 change their own passwords via the GUI.
107
108 LDAP::
109 It is possible to authenticate users via an LDAP server (e.g.
110 openldap). The server and an optional fallback server can be
111 configured and the connection can be encrypted via SSL.
112 +
113 Users are searched under a 'Base Domain Name' (`base_dn`), with the
114 user name found in the attribute specified in the 'User Attribute Name'
115 (`user_attr`) field.
116 +
117 For instance, if a user is represented via the
118 following ldif dataset:
119 +
120 ----
121 # user1 of People at ldap-test.com
122 dn: uid=user1,ou=People,dc=ldap-test,dc=com
123 objectClass: top
124 objectClass: person
125 objectClass: organizationalPerson
126 objectClass: inetOrgPerson
127 uid: user1
128 cn: Test User 1
129 sn: Testers
130 description: This is the first test user.
131 ----
132 +
133 The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
134 attribute would be `uid`.
135 +
136 If {pve} needs to authenticate (bind) to the ldap server before being
137 able to query and authenticate users, a bind domain name can be
138 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
139 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
140 (e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
141 single line containing the raw password.
142
143 Microsoft Active Directory::
144
145 A server and authentication domain need to be specified. Like with
146 ldap an optional fallback server, optional port, and SSL
147 encryption can be configured.
148
149
150 Two factor authentication
151 -------------------------
152
153 There are two ways to use two factor authentication:
154
155 It can be required by the authentication realm, either via 'TOTP' or
156 'YubiKey OTP'. In this case a newly created user needs their keys added
157 immediately as there is no way to log in without the second factor. In the case
158 of 'TOTP' a user can also change the 'TOTP' later on provided they can log in
159 first.
160
161 Alternatively a user can choose to opt into two factor authentication via 'TOTP'
162 later on even if the realm does not enforce it. As another option, if the server
163 has an 'AppId' configured, a user can opt into 'U2F' authentication, provided
164 the realm does not enforce any other second factor.
165
166 Realm enforced two factor authentication
167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168
169 This can be done by selecting one of the available methods
170 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
171 When a realm has TFA enabled it becomes a requirement and only users with
172 configured TFA will be able to login.
173
174 Currently there are two methods available:
175
176 Time based OATH (TOTP)::
177 This uses the standard HMAC-SHA1 algorithm where the current time is hashed
178 with the user's configured key. The time step and password length
179 parameters are configured.
180 +
181 A user can have multiple keys configured (separated by spaces), and the
182 keys can be specified in Base32 (RFC3548) or hexadecimal notation.
183 +
184 {pve} provides a key generation tool (`oathkeygen`) which prints out a
185 random key in Base32 notation which can be used directly with various OTP
186 tools, such as the `oathtool` command line tool, the Google authenticator
187 or FreeOTP Android apps.
188
189 YubiKey OTP::
190 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
191 server URL must be configured, and users must have a YubiKey available. In
192 order to get the key ID from a YubiKey, you can trigger the YubiKey once
193 after connecting it to USB and copy the first 12 characters of the typed
194 password into the user's 'Key IDs' field.
195 +
196 Please refer to the
197 https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
198 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
199 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
200 host your own verification server].
201
202 User configured TOTP authentication
203 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
204
205 A user can choose to use 'TOTP' as a second factor on login via the 'TFA' button
206 in the user list, unless the realm enforces 'YubiKey OTP'.
207
208 After opening the 'TFA' window, the user is presented with a dialog to setup
209 'TOTP' authentication. The 'Secret' field contains the key, which can simply be
210 generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be
211 added to provide information to the 'TOTP' app what the key belongs to.
212 Most 'TOTP' apps will show the issuer name together with the corresponding
213 'OTP' values. The user name is also included in the QR code for the 'TOTP' app.
214
215 After generating a key, a QR code will be displayed which can be used with most
216 OTP apps such as FreeOTP. Now the user needs to verify both the current user
217 password (unless logged in as 'root'), as well as the ability to correctly use
218 the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
219 field before pressing the 'Apply' button.
220
221 Server side U2F configuration
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223
224 To allow users to use 'U2F' authentication, the server needs to have a valid
225 domain with a valid https certificate. Initially an 'AppId'
226 footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
227 needs to be configured.
228
229 NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
230 unusable!
231
232 This is done via `/etc/pve/datacenter.cfg`, for instance:
233
234 ----
235 u2f: appid=https://mypve.example.com:8006
236 ----
237
238 For a single node, the 'AppId' can simply be the web UI address exactly as it
239 is used in the browser, including the 'https://' and the port as shown above.
240 Please note that some browsers may be more strict than others when matching
241 'AppIds'.
242
243 When using multiple nodes, it is best to have a separate `https` server
244 providing an `appid.json`
245 footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
246 file, as it seems to be compatible with most
247 browsers. If all nodes use subdomains of the same top level domain, it may be
248 enough to use the TLD as 'AppId', but note that some browsers may not accept
249 this.
250
251 NOTE: A bad 'AppId' will usually produce an error, but we have encountered
252 situation where this does not happen, particularly when using a top level domain
253 'AppId' for a node accessed via a subdomain in Chromium. For this reason it is
254 recommended to test the configuration with multiple browsers, as changing the
255 'AppId' later will render existing 'U2F' registrations unusable.
256
257 Activating U2F as a user
258 ~~~~~~~~~~~~~~~~~~~~~~~~
259
260 To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
261 current password (unless logged in as root), and press the 'Register' button.
262 If the server is setup correctly and the browser accepted the server's provided
263 'AppId', a message will appear prompting the user to press the button on the
264 'U2F' device (if it is a 'YubiKey' the button light should be toggling off and
265 on steadily around twice per second).
266
267 Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
268 before they can use a 'U2F' token.
269
270 [[pveum_permission_management]]
271 Permission Management
272 ---------------------
273
274 In order for a user to perform an action (such as listing, modifying or
275 deleting a parts of a VM configuration), the user needs to have the
276 appropriate permissions.
277
278 {pve} uses a role and path based permission management system. An entry in
279 the permissions table allows a user or group to take on a specific role
280 when accessing an 'object' or 'path'. This means an such an access rule can
281 be represented as a triple of '(path, user, role)' or '(path, group,
282 role)', with the role containing a set of allowed actions, and the path
283 representing the target of these actions.
284
285
286 [[pveum_roles]]
287 Roles
288 ~~~~~
289
290 A role is simply a list of privileges. Proxmox VE comes with a number
291 of predefined roles which satisfies most needs.
292
293 * `Administrator`: has all privileges
294 * `NoAccess`: has no privileges (used to forbid access)
295 * `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
296 * `PVEAuditor`: read only access
297 * `PVEDatastoreAdmin`: create and allocate backup space and templates
298 * `PVEDatastoreUser`: allocate backup space and view storage
299 * `PVEPoolAdmin`: allocate pools
300 * `PVESysAdmin`: User ACLs, audit, system console and system logs
301 * `PVETemplateUser`: view and clone templates
302 * `PVEUserAdmin`: user administration
303 * `PVEVMAdmin`: fully administer VMs
304 * `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
305
306 You can see the whole set of predefined roles on the GUI.
307
308 Adding new roles can be done via both GUI and the command line, like
309 this:
310
311 [source,bash]
312 ----
313 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
314 pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
315 ----
316
317
318 Privileges
319 ~~~~~~~~~~
320
321 A privilege is the right to perform a specific action. To simplify
322 management, lists of privileges are grouped into roles, which can then
323 be used in the permission table. Note that privileges cannot directly be
324 assigned to users and paths without being part of a role.
325
326 We currently use the following privileges:
327
328 Node / System related privileges::
329
330 * `Permissions.Modify`: modify access permissions
331 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
332 * `Sys.Console`: console access to Node
333 * `Sys.Syslog`: view Syslog
334 * `Sys.Audit`: view node status/config, Corosync cluster config and HA config
335 * `Sys.Modify`: create/remove/modify node network parameters
336 * `Group.Allocate`: create/remove/modify groups
337 * `Pool.Allocate`: create/remove/modify a pool
338 * `Realm.Allocate`: create/remove/modify authentication realms
339 * `Realm.AllocateUser`: assign user to a realm
340 * `User.Modify`: create/remove/modify user access and details.
341
342 Virtual machine related privileges::
343
344 * `VM.Allocate`: create/remove new VM to server inventory
345 * `VM.Migrate`: migrate VM to alternate server on cluster
346 * `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
347 * `VM.Console`: console access to VM
348 * `VM.Monitor`: access to VM monitor (kvm)
349 * `VM.Backup`: backup/restore VMs
350 * `VM.Audit`: view VM config
351 * `VM.Clone`: clone/copy a VM
352 * `VM.Config.Disk`: add/modify/delete Disks 
353 * `VM.Config.CDROM`: eject/change CDROM
354 * `VM.Config.CPU`: modify CPU settings
355 * `VM.Config.Memory`: modify Memory settings
356 * `VM.Config.Network`: add/modify/delete Network devices
357 * `VM.Config.HWType`: modify emulated HW type
358 * `VM.Config.Options`: modify any other VM configuration
359 * `VM.Snapshot`: create/remove VM snapshots
360
361 Storage related privileges::
362
363 * `Datastore.Allocate`: create/remove/modify a data store, delete volumes
364 * `Datastore.AllocateSpace`: allocate space on a datastore
365 * `Datastore.AllocateTemplate`: allocate/upload templates and iso images 
366 * `Datastore.Audit`: view/browse a datastore
367
368
369 Objects and Paths
370 ~~~~~~~~~~~~~~~~~
371
372 Access permissions are assigned to objects, such as a virtual machines,
373 storages or pools of resources.
374 We use file system like paths to address these objects. These paths form a
375 natural tree, and permissions of higher levels (shorter path) can
376 optionally be propagated down within this hierarchy.
377
378 [[pveum_templated_paths]]
379 Paths can be templated. When an API call requires permissions on a
380 templated path, the path may contain references to parameters of the API
381 call. These references are specified in curly braces. Some parameters are
382 implicitly taken from the API call's URI. For instance the permission path
383 `/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on
384 `/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl`
385 refers to the method's `path` parameter.
386
387 Some examples are:
388
389 * `/nodes/{node}`: Access to {pve} server machines
390 * `/vms`: Covers all VMs
391 * `/vms/{vmid}`: Access to specific VMs
392 * `/storage/{storeid}`: Access to a storages
393 * `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>
394 * `/access/groups`: Group administration
395 * `/access/realms/{realmid}`: Administrative access to realms
396
397
398 Inheritance
399 ^^^^^^^^^^^
400
401 As mentioned earlier, object paths form a file system like tree, and
402 permissions can be inherited down that tree (the propagate flag is set
403 by default). We use the following inheritance rules:
404
405 * Permissions for individual users always replace group permissions.
406 * Permissions for groups apply when the user is member of that group.
407 * Permissions replace the ones inherited from an upper level.
408
409
410 [[pveum_pools]]
411 Pools
412 ~~~~~
413
414 Pools can be used to group a set of virtual machines and data
415 stores. You can then simply set permissions on pools (`/pool/{poolid}`),
416 which are inherited to all pool members. This is a great way simplify
417 access control.
418
419
420 What permission do I need?
421 ~~~~~~~~~~~~~~~~~~~~~~~~~~
422
423 The required API permissions are documented for each individual
424 method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
425
426 The permissions are specified as a list which can be interpreted as a
427 tree of logic and access-check functions:
428
429 `["and", <subtests>...]` and `["or", <subtests>...]`::
430 Each(`and`) or any(`or`) further element in the current list has to be true.
431
432 `["perm", <path>, [ <privileges>... ], <options>...]`::
433 The `path` is a templated parameter (see
434 <<pveum_templated_paths,Objects and Paths>>). All (or , if the `any`
435 option is used, any) of the listed
436 privileges must be allowed on the specified path. If a `require-param`
437 option is specified, then its specified parameter is required even if the
438 API call's schema otherwise lists it as being optional.
439
440 `["userid-group", [ <privileges>... ], <options>...]`::
441 The caller must have any of the listed privileges on `/access/groups`. In
442 addition there are two possible checks depending on whether the
443 `groups_param` option is set:
444 +
445 * `groups_param` is set: The API call has a non-optional `groups` parameter
446 and the caller must have any of the listed privileges on all of the listed
447 groups.
448 * `groups_param` is not set: The user passed via the `userid` parameter
449 must exist and be part of a group on which the caller has any of the listed
450 privileges (via the `/access/groups/<group>` path).
451
452 `["userid-param", "self"]`::
453 The value provided for the API call's `userid` parameter must refer to the
454 user performing the action. (Usually in conjunction with `or`, to allow
455 users to perform an action on themselves even if they don't have elevated
456 privileges.)
457
458 `["userid-param", "Realm.AllocateUser"]`::
459 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
460 `<realm>` referring to the realm of the user passed via the `userid`
461 parameter. Note that the user does not need to exist in order to be
462 associated with a realm, since user IDs are passed in the form of
463 `<username>@<realm>`.
464
465 `["perm-modify", <path>]`::
466 The `path` is a templated parameter (see
467 <<pveum_templated_paths,Objects and Paths>>). The user needs either the
468 `Permissions.Modify` privilege, or,
469 depending on the path, the following privileges as a possible substitute:
470 +
471 * `/storage/...`: additionally requires 'Datastore.Allocate`
472 * `/vms/...`: additionally requires 'VM.Allocate`
473 * `/pool/...`: additionally requires 'Pool.Allocate`
474 +
475 If the path is empty, `Permission.Modify` on `/access` is required.
476
477 Command Line Tool
478 -----------------
479
480 Most users will simply use the GUI to manage users. But there is also
481 a full featured command line tool called `pveum` (short for ``**P**roxmox
482 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
483 line tools are wrappers around the API, so you can also access those
484 function through the REST API.
485
486 Here are some simple usage examples. To show help type:
487
488 [source,bash]
489  pveum
490
491 or (to show detailed help about a specific command)
492
493 [source,bash]
494  pveum help useradd
495
496 Create a new user:
497
498 [source,bash]
499  pveum useradd testuser@pve -comment "Just a test"
500
501 Set or Change the password (not all realms support that):
502
503 [source,bash]
504  pveum passwd testuser@pve
505
506 Disable a user:
507
508 [source,bash]
509  pveum usermod testuser@pve -enable 0
510
511 Create a new group:
512
513 [source,bash]
514  pveum groupadd testgroup
515
516 Create a new role:
517
518 [source,bash]
519  pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
520
521
522 Real World Examples
523 -------------------
524
525
526 Administrator Group
527 ~~~~~~~~~~~~~~~~~~~
528
529 One of the most wanted features was the ability to define a group of
530 users with full administrator rights (without using the root account).
531
532 Define the group:
533
534 [source,bash]
535  pveum groupadd admin -comment "System Administrators"
536
537 Then add the permission:
538
539 [source,bash]
540  pveum aclmod / -group admin -role Administrator
541
542 You can finally add users to the new 'admin' group:
543
544 [source,bash]
545  pveum usermod testuser@pve -group admin
546
547
548 Auditors
549 ~~~~~~~~
550
551 You can give read only access to users by assigning the `PVEAuditor`
552 role to users or groups.
553
554 Example1: Allow user `joe@pve` to see everything
555
556 [source,bash]
557  pveum aclmod / -user joe@pve -role PVEAuditor
558
559 Example1: Allow user `joe@pve` to see all virtual machines
560
561 [source,bash]
562  pveum aclmod /vms -user joe@pve -role PVEAuditor
563
564
565 Delegate User Management
566 ~~~~~~~~~~~~~~~~~~~~~~~~
567
568 If you want to delegate user management to user `joe@pve` you can do
569 that with:
570
571 [source,bash]
572  pveum aclmod /access -user joe@pve -role PVEUserAdmin
573
574 User `joe@pve` can now add and remove users, change passwords and
575 other user attributes. This is a very powerful role, and you most
576 likely want to limit that to selected realms and groups. The following
577 example allows `joe@pve` to modify users within realm `pve` if they
578 are members of group `customers`:
579
580 [source,bash]
581  pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
582  pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
583
584 NOTE: The user is able to add other users, but only if they are
585 members of group `customers` and within realm `pve`.
586
587
588 Pools
589 ~~~~~
590
591 An enterprise is usually structured into several smaller departments,
592 and it is common that you want to assign resources to them and
593 delegate management tasks. A pool is simply a set of virtual machines
594 and data stores. You can create pools on the GUI. After that you can
595 add resources to the pool (VMs, Storage).
596
597 You can also assign permissions to the pool. Those permissions are
598 inherited to all pool members.
599
600 Lets assume you have a software development department, so we first
601 create a group
602
603 [source,bash]
604  pveum groupadd developers -comment "Our software developers"
605
606 Now we create a new user which is a member of that group
607
608 [source,bash]
609  pveum useradd developer1@pve -group developers -password
610
611 NOTE: The -password parameter will prompt you for a password
612
613 I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
614
615 [source,bash]
616  pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
617
618 Our software developers can now administrate the resources assigned to
619 that pool.
620
621
622 ifdef::manvolnum[]
623 include::pve-copyright.adoc[]
624 endif::manvolnum[]
625