describe two factor authentication
[pve-docs.git] / pveum.adoc
CommitLineData
3c8533f2
DM
1ifdef::manvolnum[]
2PVE({manvolnum})
3================
38fd0958 4include::attributes.txt[]
3c8533f2
DM
5
6NAME
7----
8
9pveum - Proxmox VE User Manager
10
11
12SYNOPSYS
13--------
14
15include::pveum.1-synopsis.adoc[]
16
17
18DESCRIPTION
19-----------
20endif::manvolnum[]
21
22ifndef::manvolnum[]
23User Management
24===============
38fd0958 25include::attributes.txt[]
3c8533f2
DM
26endif::manvolnum[]
27
28// Copied from pve wiki: Revision as of 16:10, 27 October 2015
29
30Proxmox VE supports multiple authentication sources, e.g. Microsoft
31Active Directory, LDAP, Linux PAM or the integrated Proxmox VE
32authentication server.
33
34By using the role based user- and permission management for all
5eba0743
FG
35objects (VMs, storages, nodes, etc.) granular access can be defined.
36
3c8533f2 37
d6614202 38[[authentication-realms]]
3c8533f2
DM
39Authentication Realms
40---------------------
41
d6614202
WB
42As {pve} users are just counterparts for users existing on some external
43realm, the realms have to be configured in `/etc/pve/domains.cfg`.
44The following realms (authentication methods) are available:
3c8533f2
DM
45
46Linux PAM standard authentication::
d6614202
WB
47In this case a system user has to exist (eg. created via the `adduser`
48command) on all nodes the user is allowed to login, and the user
49authenticates with their usual system password.
50+
3c8533f2
DM
51[source,bash]
52----
53useradd heinz
54passwd heinz
55groupadd watchman
56usermod -a -G watchman heinz
57----
58
59Proxmox VE authentication server::
d6614202
WB
60This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
61Password are encrypted using the SHA-256 hash method.
62This is the most convenient method for for small (or even medium)
63installations where users do not need access to anything outside of
64{pve}. In this case users are fully managed by {pve} and are able to
65change their own passwords via the GUI.
66
67LDAP::
68It is possible to authenticate users via an LDAP server (eq.
69openldap). The server and an optional fallback server can be
70configured and the connection can be encrypted via SSL.
71+
72Users are searched under a 'Base Domain Name' (`base_dn`), with the
73user name found in the attribute specified in the 'User Attribute Name'
74(`user_attr`) field.
75+
76For instance, if a user is represented via the
77following ldif dataset:
78+
79----
80# user1 of People at ldap-test.com
81dn: uid=user1,ou=People,dc=ldap-test,dc=com
82objectClass: top
83objectClass: person
84objectClass: organizationalPerson
85objectClass: inetOrgPerson
86uid: user1
87cn: Test User 1
88sn: Testers
89description: This is the first test user.
90----
91+
92The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user
93attribute would be `uid`.
94+
95If {pve} needs to authenticate (bind) to the ldap server before being
96able to query and authenticate users, a bind domain name can be
97configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
98password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
99(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
100single line containing the raw password.
101
102Microsoft Active Directory::
3c8533f2 103
d6614202
WB
104A server and authentication domain need to be specified. Like with
105ldap an optional fallback server, optional port, and SSL
106encryption can be configured.
3c8533f2 107
5eba0743 108
9e8f2770
WB
109Two factor authentication
110-------------------------
111
112Each realm can optionally be secured additionally by two factor
113authentication. This can be done by selecting one of the available methods
114via the 'TFA' dropdown box when adding or editing an Authentication Realm.
115When a realm has TFA enabled it becomes a requirement and only users with
116configured TFA will be able to login.
117
118Currently there are two methods available:
119
120Time based OATH (TOTP)::
121This uses the standard HMAC-SHA1 algorithm where the current time is hashed
122with the user's configured key. The time step and password length
123parameters are configured.
124+
125A user can have multiple keys configured (separated by spaces), and the
126keys can be specified in Base32 (RFC3548) or hexadecimal notation.
127+
128{pve} provides a key generation tool (`oathkeygen`) which prints out a
129random key in Base32 notation which can be used directly with various OTP
130tools, such as the `oathtool` command line tool, the Google authenticator
131or FreeOTP Android apps.
132
133YubiKey OTP::
134For authenticating via a YubiKey a Yubico API ID, API KEY and validation
135server URL must be configured, and users must have a YubiKey available. In
136order to get the key ID from a YubiKey, you can trigger the YubiKey once
137after connecting it to USB and copy the first 12 characters of the typed
138password into the user's 'Key IDs' field.
139+
140Please refer to the
141https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
142https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
143https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
144host your own verification server].
145
146
3c8533f2
DM
147Terms and Definitions
148---------------------
149
5eba0743 150
3c8533f2
DM
151Users
152~~~~~
153
154A Proxmox VE user name consists of two parts: `<userid>@<realm>`. The
155login screen on the GUI shows them a separate items, but it is
156internally used as single string.
157
8c1189b6 158We store the following attribute for users (`/etc/pve/user.cfg`):
3c8533f2
DM
159
160* first name
161* last name
162* email address
163* expiration date
164* flag to enable/disable account
165* comment
166
5eba0743 167
3c8533f2
DM
168Superuser
169^^^^^^^^^
170
8c1189b6 171The traditional unix superuser account is called `root@pam`. All
3c8533f2
DM
172system mails are forwarded to the email assigned to that account.
173
5eba0743 174
3c8533f2
DM
175Groups
176~~~~~~
177
178Each user can be member of several groups. Groups are the preferred
179way to organize access permissions. You should always grant permission
180to groups instead of using individual users. That way you will get a
181much shorter access control list which is easier to handle.
182
5eba0743 183
3c8533f2
DM
184Objects and Paths
185~~~~~~~~~~~~~~~~~
186
187Access permissions are assigned to objects, such as a virtual machines
8c1189b6
FG
188(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of
189resources (`/pool/{poolname}`). We use file system like paths to
3c8533f2
DM
190address those objects. Those paths form a natural tree, and
191permissions can be inherited down that hierarchy.
192
5eba0743 193
3c8533f2
DM
194Privileges
195~~~~~~~~~~
196
197A privilege is the right to perform a specific action. To simplify
198management, lists of privileges are grouped into roles, which can then
199be uses to set permissions.
200
201We currently use the following privileges:
202
203Node / System related privileges::
204
205* `Permissions.Modify`: modify access permissions
206* `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
207* `Sys.Console`: console access to Node
208* `Sys.Syslog`: view Syslog
209* `Sys.Audit`: view node status/config
210* `Sys.Modify`: create/remove/modify node network parameters
211* `Group.Allocate`: create/remove/modify groups
212* `Pool.Allocate`: create/remove/modify a pool
213* `Realm.Allocate`: create/remove/modify authentication realms
214* `Realm.AllocateUser`: assign user to a realm
215* `User.Modify`: create/remove/modify user access and details.
216
217Virtual machine related privileges::
218
219* `VM.Allocate`: create/remove new VM to server inventory
220* `VM.Migrate`: migrate VM to alternate server on cluster
221* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
222* `VM.Console`: console access to VM
223* `VM.Monitor`: access to VM monitor (kvm)
224* `VM.Backup`: backup/restore VMs
225* `VM.Audit`: view VM config
226* `VM.Clone`: clone/copy a VM
227* `VM.Config.Disk`: add/modify/delete Disks
228* `VM.Config.CDROM`: eject/change CDROM
229* `VM.Config.CPU`: modify CPU settings
230* `VM.Config.Memory`: modify Memory settings
231* `VM.Config.Network`: add/modify/delete Network devices
232* `VM.Config.HWType`: modify emulated HW type
233* `VM.Config.Options`: modify any other VM configuration
234* `VM.Snapshot`: create/remove VM snapshots
235
236Storage related privileges::
237
238* `Datastore.Allocate`: create/remove/modify a data store, delete volumes
239* `Datastore.AllocateSpace`: allocate space on a datastore
240* `Datastore.AllocateTemplate`: allocate/upload templates and iso images
241* `Datastore.Audit`: view/browse a datastore
242
5eba0743 243
3c8533f2
DM
244Roles
245~~~~~
246
247A role is simply a list of privileges. Proxmox VE comes with a number
248of predefined roles which satisfies most needs.
249
250* `Administrator`: has all privileges
251* `NoAccess`: has no privileges (used to forbid access)
252* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`).
253* `PVEAuditor`: read only access
254* `PVEDatastoreAdmin`: create and allocate backup space and templates
255* `PVEDatastoreUser`: allocate backup space and view storage
256* `PVEPoolAdmin`: allocate pools
257* `PVESysAdmin`: User ACLs, audit, system console and system logs
258* `PVETemplateUser`: view and clone templates
259* `PVEUserAdmin`: user administration
260* `PVEVMAdmin`: fully administer VMs
261* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management
262
263You can see the whole set of predefined roles on the GUI.
264
265Adding new roles using the CLI:
266
267[source,bash]
268----
269pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
270pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console"
271----
272
273
274Permissions
275~~~~~~~~~~~
276
277Permissions are the way we control access to objects. In technical
278terms they are simply a triple containing `<path,user,role>`. This
279concept is also known as access control lists. Each permission
280specifies a subject (user or group) and a role (set of privileges) on
281a specific path.
282
283When a subject requests an action on an object, the framework looks up
284the roles assigned to that subject (using the object path). The set of
285roles defines the granted privileges.
286
5eba0743 287
3c8533f2
DM
288Inheritance
289^^^^^^^^^^^
290
5eba0743 291As mentioned earlier, object paths form a file system like tree, and
3c8533f2
DM
292permissions can be inherited down that tree (the propagate flag is set
293by default). We use the following inheritance rules:
294
295* permission for individual users always overwrite group permission.
296* permission for groups apply when the user is member of that group.
297* permission set at higher level always overwrites inherited permissions.
298
5eba0743 299
3c8533f2
DM
300What permission do I need?
301^^^^^^^^^^^^^^^^^^^^^^^^^^
4b048bf2
EK
302
303The required API permissions are documented for each individual
304method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/
3c8533f2 305
5eba0743 306
3c8533f2
DM
307Pools
308~~~~~
309
310Pools can be used to group a set of virtual machines and data
8c1189b6 311stores. You can then simply set permissions on pools (`/pool/{poolid}`),
3c8533f2
DM
312which are inherited to all pool members. This is a great way simplify
313access control.
314
315Command Line Tool
316-----------------
317
318Most users will simply use the GUI to manage users. But there is also
8c1189b6 319a full featured command line tool called `pveum` (short for ``**P**roxmox
4f6e7e05
WB
320**VE** **U**ser **M**anager''). Please note that all Proxmox VE command
321line tools are wrappers around the API, so you can also access those
322function through the REST API.
3c8533f2
DM
323
324Here are some simple usage examples. To show help type:
325
326[source,bash]
327 pveum
328
329or (to show detailed help about a specific command)
330
331[source,bash]
332 pveum help useradd
333
334Create a new user:
335
336[source,bash]
337 pveum useradd testuser@pve -comment "Just a test"
338
339Set or Change the password (not all realms support that):
340
341[source,bash]
342 pveum passwd testuser@pve
343
344Disable a user:
345
346[source,bash]
347 pveum usermod testuser@pve -enable 0
348
349Create a new group:
350
351[source,bash]
352 pveum groupadd testgroup
353
354Create a new role:
355
356[source,bash]
357 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
358
359
360Real World Examples
361-------------------
362
5eba0743 363
3c8533f2
DM
364Administrator Group
365~~~~~~~~~~~~~~~~~~~
366
367One of the most wanted features was the ability to define a group of
5eba0743 368users with full administrator rights (without using the root account).
3c8533f2
DM
369
370Define the group:
371
372[source,bash]
373 pveum groupadd admin -comment "System Administrators"
374
375Then add the permission:
376
377[source,bash]
378 pveum aclmod / -group admin -role Administrator
379
380You can finally add users to the new 'admin' group:
381
382[source,bash]
383 pveum usermod testuser@pve -group admin
384
385
386Auditors
387~~~~~~~~
388
389You can give read only access to users by assigning the `PVEAuditor`
390role to users or groups.
391
8c1189b6 392Example1: Allow user `joe@pve` to see everything
3c8533f2
DM
393
394[source,bash]
395 pveum aclmod / -user joe@pve -role PVEAuditor
396
8c1189b6 397Example1: Allow user `joe@pve` to see all virtual machines
3c8533f2
DM
398
399[source,bash]
400 pveum aclmod /vms -user joe@pve -role PVEAuditor
401
5eba0743 402
3c8533f2
DM
403Delegate User Management
404~~~~~~~~~~~~~~~~~~~~~~~~
405
8c1189b6 406If you want to delegate user managenent to user `joe@pve` you can do
3c8533f2
DM
407that with:
408
409[source,bash]
410 pveum aclmod /access -user joe@pve -role PVEUserAdmin
411
8c1189b6 412User `joe@pve` can now add and remove users, change passwords and
3c8533f2
DM
413other user attributes. This is a very powerful role, and you most
414likely want to limit that to selected realms and groups. The following
8c1189b6
FG
415example allows `joe@pve` to modify users within realm `pve` if they
416are members of group `customers`:
3c8533f2
DM
417
418[source,bash]
419 pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
420 pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
421
0abc65b0 422NOTE: The user is able to add other users, but only if they are
8c1189b6
FG
423members of group `customers` and within realm `pve`.
424
3c8533f2
DM
425
426Pools
427~~~~~
428
429An enterprise is usually structured into several smaller departments,
430and it is common that you want to assign resources to them and
431delegate management tasks. A pool is simply a set of virtual machines
432and data stores. You can create pools on the GUI. After that you can
433add resources to the pool (VMs, Storage).
434
435You can also assign permissions to the pool. Those permissions are
436inherited to all pool members.
437
438Lets assume you have a software development department, so we first
439create a group
440
441[source,bash]
442 pveum groupadd developers -comment "Our software developers"
443
444Now we create a new user which is a member of that group
445
446[source,bash]
447 pveum useradd developer1@pve -group developers -password
448
0abc65b0 449NOTE: The -password parameter will prompt you for a password
3c8533f2 450
8c1189b6 451I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
3c8533f2
DM
452
453[source,bash]
454 pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
455
456Our software developers can now administrate the resources assigned to
457that pool.
458
459
460ifdef::manvolnum[]
461include::pve-copyright.adoc[]
462endif::manvolnum[]
463