Update TFA documentation

[pve-docs.git] / pveum.adoc

diff --git a/pveum.adoc b/pveum.adoc
index 74355466009da2675a09fe5263c20fc06e90eab7..1447d3832b04b23459f2ea0a7a68665a0b837139 100644 (file)
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -1,8 +1,7 @@
+[[chapter_user_management]]

 ifdef::manvolnum[]
 ifdef::manvolnum[]

-PVE(1)
-======
-include::attributes.txt[]
-
+pveum(1)
+========

 :pve-toplevel:
 
 NAME
 :pve-toplevel:
 
 NAME


@@ -20,16 +19,11 @@ include::pveum.1-synopsis.adoc[]
 DESCRIPTION
 -----------
 endif::manvolnum[]
 DESCRIPTION
 -----------
 endif::manvolnum[]

-

 ifndef::manvolnum[]
 User Management
 ===============
 ifndef::manvolnum[]
 User Management
 ===============

-include::attributes.txt[]
-endif::manvolnum[]
-
-ifdef::wiki[]

 :pve-toplevel:
 :pve-toplevel:

-endif::wiki[]
+endif::manvolnum[]

 
 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
 
 
 // Copied from pve wiki: Revision as of 16:10, 27 October 2015
 


@@ -41,12 +35,13 @@ By using the role based user- and permission management for all
 objects (VMs, storages, nodes, etc.) granular access can be defined.
 
 
 objects (VMs, storages, nodes, etc.) granular access can be defined.
 
 

+[[pveum_users]]

 Users
 -----
 
 {pve} stores user attributes in `/etc/pve/user.cfg`.
 Passwords are not stored here, users are instead associated with
 Users
 -----
 
 {pve} stores user attributes in `/etc/pve/user.cfg`.
 Passwords are not stored here, users are instead associated with

-<<authentication-realms,authentication realms>> described below.
+<<pveum_authentication_realms,authentication realms>> described below.

 Therefore a user is internally often identified by its name and
 realm in the form `<userid>@<realm>`.
 
 Therefore a user is internally often identified by its name and
 realm in the form `<userid>@<realm>`.
 


@@ -71,6 +66,7 @@ still be changed and system mails will be sent to the email address
 assigned to this user.
 
 
 assigned to this user.
 
 

+[[pveum_groups]]

 Groups
 ~~~~~~
 
 Groups
 ~~~~~~
 


@@ -80,7 +76,7 @@ to groups instead of using individual users. That way you will get a
 much shorter access control list which is easier to handle.
 
 
 much shorter access control list which is easier to handle.
 
 

-[[authentication-realms]]
+[[pveum_authentication_realms]]

 Authentication Realms
 ---------------------
 
 Authentication Realms
 ---------------------
 


@@ -89,7 +85,7 @@ realm, the realms have to be configured in `/etc/pve/domains.cfg`.
 The following realms (authentication methods) are available:
 
 Linux PAM standard authentication::
 The following realms (authentication methods) are available:
 
 Linux PAM standard authentication::

-In this case a system user has to exist (eg. created via the `adduser`
+In this case a system user has to exist (e.g. created via the `adduser`

 command) on all nodes the user is allowed to login, and the user
 authenticates with their usual system password.
 +
 command) on all nodes the user is allowed to login, and the user
 authenticates with their usual system password.
 +


@@ -104,13 +100,13 @@ usermod -a -G watchman heinz
 Proxmox VE authentication server::
 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
 Password are encrypted using the SHA-256 hash method.
 Proxmox VE authentication server::
 This is a unix like password store (`/etc/pve/priv/shadow.cfg`).
 Password are encrypted using the SHA-256 hash method.

-This is the most convenient method for for small (or even medium)
+This is the most convenient method for small (or even medium)

 installations where users do not need access to anything outside of
 {pve}. In this case users are fully managed by {pve} and are able to
 change their own passwords via the GUI.
 
 LDAP::
 installations where users do not need access to anything outside of
 {pve}. In this case users are fully managed by {pve} and are able to
 change their own passwords via the GUI.
 
 LDAP::

-It is possible to authenticate users via an LDAP server (eq.
+It is possible to authenticate users via an LDAP server (e.g.

 openldap). The server and an optional fallback server can be
 configured and the connection can be encrypted via SSL.
 +
 openldap). The server and an optional fallback server can be
 configured and the connection can be encrypted via SSL.
 +


@@ -141,7 +137,7 @@ If {pve} needs to authenticate (bind) to the ldap server before being
 able to query and authenticate users, a bind domain name can be
 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`
 able to query and authenticate users, a bind domain name can be
 configured via the `bind_dn` property in `/etc/pve/domains.cfg`. Its
 password then has to be stored in `/etc/pve/priv/ldap/<realmname>.pw`

-(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+(e.g. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a

 single line containing the raw password.
 
 Microsoft Active Directory::
 single line containing the raw password.
 
 Microsoft Active Directory::


@@ -154,8 +150,23 @@ encryption can be configured.
 Two factor authentication
 -------------------------
 
 Two factor authentication
 -------------------------
 

-Each realm can optionally be secured additionally by two factor
-authentication. This can be done by selecting one of the available methods
+There are two ways to use two factor authentication:
+
+It can be required by the authentication realm, either via 'TOTP' or
+'YubiKey OTP'. In this case a newly created user needs their keys added
+immediately as there is no way to log in without the second factor. In the case
+of 'TOTP' a user can also change the 'TOTP' later on provided they can log in
+first.
+
+Alternatively a user can choose to opt into two factor authentication via 'TOTP'
+later on even if the realm does not enforce it. As another option, if the server
+has an 'AppId' configured, a user can opt into 'U2F' authentication, provided
+the realm does not enforce any other second factor.
+
+Realm enforced two factor authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This can be done by selecting one of the available methods

 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
 When a realm has TFA enabled it becomes a requirement and only users with
 configured TFA will be able to login.
 via the 'TFA' dropdown box when adding or editing an Authentication Realm.
 When a realm has TFA enabled it becomes a requirement and only users with
 configured TFA will be able to login.


@@ -188,7 +199,75 @@ https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
 host your own verification server].
 
 https://developers.yubico.com/Software_Projects/YubiKey_OTP/YubiCloud_Validation_Servers/[
 host your own verification server].
 

+User configured TOTP authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A user can choose to use 'TOTP' as a second factor on login via the 'TFA' button
+in the user list, unless the realm enforces 'YubiKey OTP'.
+
+After opening the 'TFA' window, the user is presented with a dialog to setup
+'TOTP' authentication. The 'Secret' field contains the key, which can simply be
+generated randomly via the 'Randomize' button. An optional 'Issuer Name' can be
+added to provide information to the 'TOTP' app what the key belongs to.
+Most 'TOTP' apps will show the issuer name together with the corresponding
+'OTP' values. The user name is also included in the QR code for the 'TOTP' app.
+
+After generating a key, a QR code will be displayed which can be used with most
+OTP apps such as FreeOTP. Now the user needs to verify both the current user
+password (unless logged in as 'root'), as well as the ability to correctly use
+the 'TOTP' key by typing the current 'OTP' value into the 'Verification Code'
+field before pressing the 'Apply' button.
+
+Server side U2F configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To allow users to use 'U2F' authentication, the server needs to have a valid
+domain with a valid https certificate. Initially an 'AppId'
+footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
+needs to be configured.
+
+NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
+unusable!
+
+This is done via `/etc/pve/datacenter.cfg`, for instance:
+
+----
+u2f: appid=https://mypve.example.com:8006
+----
+
+For a single node, the 'AppId' can simply be the web UI address exactly as it
+is used in the browser, including the 'https://' and the port as shown above.
+Please note that some browsers may be more strict than others when matching
+'AppIds'.
+
+When using multiple nodes, it is best to have a separate `https` server
+providing an `appid.json`
+footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
+file, as it seems to be compatible with most
+browsers. If all nodes use subdomains of the same top level domain, it may be
+enough to use the TLD as 'AppId', but note that some browsers may not accept
+this.
+
+NOTE: A bad 'AppId' will usually produce an error, but we have encountered
+situation where this does not happen, particularly when using a top level domain
+'AppId' for a node accessed via a subdomain in Chromium. For this reason it is
+recommended to test the configuration with multiple browsers, as changing the
+'AppId' later will render existing 'U2F' registrations unusable.
+
+Activating U2F as a user
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
+current password (unless logged in as root), and press the 'Register' button.
+If the server is setup correctly and the browser accepted the server's provided
+'AppId', a message will appear prompting the user to press the button on the
+'U2F' device (if it is a 'YubiKey' the button light should be toggling off and
+on steadily around twice per second).
+
+Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
+before they can use a 'U2F' token.

 
 

+[[pveum_permission_management]]

 Permission Management
 ---------------------
 
 Permission Management
 ---------------------
 


@@ -204,6 +283,7 @@ role)', with the role containing a set of allowed actions, and the path
 representing the target of these actions.
 
 
 representing the target of these actions.
 
 

+[[pveum_roles]]

 Roles
 ~~~~~
 
 Roles
 ~~~~~
 


@@ -225,7 +305,7 @@ of predefined roles which satisfies most needs.
 
 You can see the whole set of predefined roles on the GUI.
 
 
 You can see the whole set of predefined roles on the GUI.
 

-Adding new roles can currently only be done from the command line, like
+Adding new roles can be done via both GUI and the command line, like

 this:
 
 [source,bash]
 this:
 
 [source,bash]


@@ -251,7 +331,7 @@ Node / System related privileges::
 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
 * `Sys.Console`: console access to Node
 * `Sys.Syslog`: view Syslog
 * `Sys.PowerMgmt`: Node power management (start, stop, reset, shutdown, ...)
 * `Sys.Console`: console access to Node
 * `Sys.Syslog`: view Syslog

-* `Sys.Audit`: view node status/config
+* `Sys.Audit`: view node status/config, Corosync cluster config and HA config

 * `Sys.Modify`: create/remove/modify node network parameters
 * `Group.Allocate`: create/remove/modify groups
 * `Pool.Allocate`: create/remove/modify a pool
 * `Sys.Modify`: create/remove/modify node network parameters
 * `Group.Allocate`: create/remove/modify groups
 * `Pool.Allocate`: create/remove/modify a pool


@@ -295,7 +375,7 @@ We use file system like paths to address these objects. These paths form a
 natural tree, and permissions of higher levels (shorter path) can
 optionally be propagated down within this hierarchy.
 
 natural tree, and permissions of higher levels (shorter path) can
 optionally be propagated down within this hierarchy.
 

-[[templated-paths]]
+[[pveum_templated_paths]]

 Paths can be templated. When an API call requires permissions on a
 templated path, the path may contain references to parameters of the API
 call. These references are specified in curly braces. Some parameters are
 Paths can be templated. When an API call requires permissions on a
 templated path, the path may contain references to parameters of the API
 call. These references are specified in curly braces. Some parameters are


@@ -310,7 +390,7 @@ Some examples are:
 * `/vms`: Covers all VMs
 * `/vms/{vmid}`: Access to specific VMs
 * `/storage/{storeid}`: Access to a storages
 * `/vms`: Covers all VMs
 * `/vms/{vmid}`: Access to specific VMs
 * `/storage/{storeid}`: Access to a storages

-* `/pool/{poolname}`: Access to VMs part of a <<resource-pools,pool>
+* `/pool/{poolname}`: Access to VMs part of a <<pveum_pools,pool>>

 * `/access/groups`: Group administration
 * `/access/realms/{realmid}`: Administrative access to realms
 
 * `/access/groups`: Group administration
 * `/access/realms/{realmid}`: Administrative access to realms
 


@@ -327,6 +407,7 @@ by default). We use the following inheritance rules:
 * Permissions replace the ones inherited from an upper level.
 
 
 * Permissions replace the ones inherited from an upper level.
 
 

+[[pveum_pools]]

 Pools
 ~~~~~
 
 Pools
 ~~~~~
 


@@ -349,14 +430,15 @@ tree of logic and access-check functions:
 Each(`and`) or any(`or`) further element in the current list has to be true.
 
 `["perm", <path>, [ <privileges>... ], <options>...]`::
 Each(`and`) or any(`or`) further element in the current list has to be true.
 
 `["perm", <path>, [ <privileges>... ], <options>...]`::

-The `path` is a templated parameter (see <<templated-paths,Objects and
-Paths>>). All (or , if the `any` option is used, any) of the listed
+The `path` is a templated parameter (see
+<<pveum_templated_paths,Objects and Paths>>). All (or , if the `any`
+option is used, any) of the listed

 privileges must be allowed on the specified path. If a `require-param`
 option is specified, then its specified parameter is required even if the
 API call's schema otherwise lists it as being optional.
 
 `["userid-group", [ <privileges>... ], <options>...]`::
 privileges must be allowed on the specified path. If a `require-param`
 option is specified, then its specified parameter is required even if the
 API call's schema otherwise lists it as being optional.
 
 `["userid-group", [ <privileges>... ], <options>...]`::

-The callermust have any of the listed privileges on `/access/groups`. In
+The caller must have any of the listed privileges on `/access/groups`. In

 addition there are two possible checks depending on whether the
 `groups_param` option is set:
 +
 addition there are two possible checks depending on whether the
 `groups_param` option is set:
 +


@@ -375,14 +457,15 @@ privileges.)
 
 `["userid-param", "Realm.AllocateUser"]`::
 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with
 
 `["userid-param", "Realm.AllocateUser"]`::
 The user needs `Realm.AllocateUser` access to `/access/realm/<realm>`, with

-`<realm>` refering to the realm of the user passed via the `userid`
+`<realm>` referring to the realm of the user passed via the `userid`

 parameter. Note that the user does not need to exist in order to be
 associated with a realm, since user IDs are passed in the form of
 `<username>@<realm>`.
 
 `["perm-modify", <path>]`::
 parameter. Note that the user does not need to exist in order to be
 associated with a realm, since user IDs are passed in the form of
 `<username>@<realm>`.
 
 `["perm-modify", <path>]`::

-The `path` is a templated parameter (see <<templated-paths,Objects and
-Paths>>). The user needs either the `Permissions.Modify` privilege, or,
+The `path` is a templated parameter (see
+<<pveum_templated_paths,Objects and Paths>>). The user needs either the
+`Permissions.Modify` privilege, or,

 depending on the path, the following privileges as a possible substitute:
 +
 * `/storage/...`: additionally requires 'Datastore.Allocate`
 depending on the path, the following privileges as a possible substitute:
 +
 * `/storage/...`: additionally requires 'Datastore.Allocate`


@@ -482,7 +565,7 @@ Example1: Allow user `joe@pve` to see all virtual machines
 Delegate User Management
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Delegate User Management
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

-If you want to delegate user managenent to user `joe@pve` you can do
+If you want to delegate user management to user `joe@pve` you can do

 that with:
 
 [source,bash]
 that with:
 
 [source,bash]