]> git.proxmox.com Git - pve-docs.git/blobdiff - pveum.adoc
projects / pve-docs.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
bump version to 6.1-4
[pve-docs.git] / pveum.adoc
diff --git a/pveum.adoc b/pveum.adoc
index b0bb72afadd4c21f6252bb1ad1978a94947a9816..59a28245c0b53003ed521dab9a02b2c2d12d77cc 100644 (file)
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -54,7 +54,7 @@ Each user entry in this file contains the following information:
 * An optional Expiration date
 * A comment or note about this user
 * Whether this user is enabled or disabled
 * An optional Expiration date
 * A comment or note about this user
 * Whether this user is enabled or disabled
-* Optional two factor authentication keys
+* Optional two-factor authentication keys
 
 
 System administrator
 
 
 System administrator
@@ -147,29 +147,45 @@ ldap an optional fallback server, optional port, and SSL
 encryption can be configured.
 
 
 encryption can be configured.
 
 
-Two factor authentication
+[[pveum_tfa_auth]]
+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
-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.
+There are two ways to use two-factor authentication:
+
+It can be required by the authentication realm, either via 'TOTP'
+(Time-based One-Time Password) 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', users can
+also change the 'TOTP' later on, provided they can log in first.
+
+Alternatively, users can choose to opt in to 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.
 
 Currently there are two methods available:
 
 
 Currently there are two methods available:
 
-Time based OATH (TOTP)::
-This uses the standard HMAC-SHA1 algorithm where the current time is hashed
-with the user's configured key. The time step and password length
-parameters are configured.
+Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm
+where the current time is hashed with the user's configured key. The
+time step and password length parameters are configured.
 +
 +
-A user can have multiple keys configured (separated by spaces), and the
-keys can be specified in Base32 (RFC3548) or hexadecimal notation.
+A user can have multiple keys configured (separated by spaces), and the keys
+can be specified in Base32 (RFC3548) or hexadecimal notation.
 +
 +
-{pve} provides a key generation tool (`oathkeygen`) which prints out a
-random key in Base32 notation which can be used directly with various OTP
-tools, such as the `oathtool` command line tool, the Google authenticator
-or FreeOTP Android apps.
+{pve} provides a key generation tool (`oathkeygen`) which prints out a random
+key in Base32 notation which can be used directly with various OTP tools, such
+as the `oathtool` command line tool, or on Android Google Authenticator,
+FreeOTP, andOTP or similar applications.
 
 YubiKey OTP::
 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
 
 YubiKey OTP::
 For authenticating via a YubiKey a Yubico API ID, API KEY and validation
@@ -177,13 +193,86 @@ server URL must be configured, and users must have a YubiKey available. In
 order to get the key ID from a YubiKey, you can trigger the YubiKey once
 after connecting it to USB and copy the first 12 characters of the typed
 password into the user's 'Key IDs' field.
 order to get the key ID from a YubiKey, you can trigger the YubiKey once
 after connecting it to USB and copy the first 12 characters of the typed
 password into the user's 'Key IDs' field.
+
 +
 +
-Please refer to the
-https://developers.yubico.com/OTP/[YubiKey OTP] documentation for how to use the
+Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
+documentation for how to use the
 https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
 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].
+
+[[pveum_user_configured_totp]]
+User configured TOTP authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can choose to enable 'TOTP' as a second factor on login via the 'TFA'
+button in the user list (unless the realm enforces 'YubiKey OTP').
+
+[thumbnail="screenshot/gui-datacenter-users-tfa.png"]
+
+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.
+
+[[pveum_configure_u2f]]
+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.
+
+[[pveum_user_configured_u2f]]
+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
 
 [[pveum_permission_management]]
 Permission Management
@@ -223,9 +312,15 @@ 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 be done via both GUI and the command line, like
-this:
+Adding new roles can be done via both GUI and the command line.
 
 
+[thumbnail="screenshot/gui-datacenter-role-add.png"]
+For the GUI just navigate to 'Permissions -> User' Tab from 'Datacenter' and
+click on the 'Create' button, there you can set a name and select all desired
+roles from the 'Privileges' dropdown box.
+
+To add a role through the command line you can use the 'pveum' CLI tool, like
+this:
 [source,bash]
 ----
 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
 [source,bash]
 ----
 pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console"
@@ -349,7 +444,7 @@ 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
 
 `["perm", <path>, [ <privileges>... ], <options>...]`::
 The `path` is a templated parameter (see
-<<pveum_templated_paths,Objects and Paths>>). All (or , if the `any`
+<<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
 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
@@ -396,10 +491,10 @@ Command Line Tool
 -----------------
 
 Most users will simply use the GUI to manage users. But there is also
 -----------------
 
 Most users will simply use the GUI to manage users. But there is also
-a full featured command line tool called `pveum` (short for ``**P**roxmox
+a fully featured command line tool called `pveum` (short for ``**P**roxmox
 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
 line tools are wrappers around the API, so you can also access those
 **VE** **U**ser **M**anager''). Please note that all Proxmox VE command
 line tools are wrappers around the API, so you can also access those
-function through the REST API.
+functions through the REST API.
 
 Here are some simple usage examples. To show help type:
 
 
 Here are some simple usage examples. To show help type:
 
PVE Documentation