* 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
to groups instead of using individual users. That way you will get a
much shorter access control list which is easier to handle.
+[[pveum_tokens]]
+API Tokens
+~~~~~~~~~~
+
+API tokens allow stateless access to most parts of the REST API by another
+system, software or API client. Tokens can be generated for individual users
+and can be given separate permissions and expiration dates to limit the scope
+and duration of the access. Should the API token get compromised it can be
+revoked without disabling the user itself.
+
+API tokens come in two basic types:
+
+* separated privileges: the token needs to be given explicit access with ACLs,
+ its effective permissions are calculated by intersecting user and token
+ permissions.
+* full privileges: the token permissions are identical to that of the
+ associated user.
+
+CAUTION: The token value is only displayed/returned once when the token is
+generated. It cannot be retrieved again over the API at a later time!
+
+To use an API token, set the HTTP header 'Authorization' to the displayed value
+of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
+refer to your API client documentation.
[[pveum_authentication_realms]]
Authentication Realms
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.
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:
-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
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://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
appropriate permissions.
{pve} uses a role and path based permission management system. An entry in
-the permissions table allows a user or group to take on a specific role
+the permissions table allows a user, group or token to take on a specific role
when accessing an 'object' or 'path'. This means an such an access rule can
-be represented as a triple of '(path, user, role)' or '(path, group,
-role)', with the role containing a set of allowed actions, and the path
-representing the target of these actions.
+be represented as a triple of '(path, user, role)', '(path, group,
+role)' or '(path, token, role)', with the role containing a set of allowed
+actions, and the path representing the target of these actions.
[[pveum_roles]]
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
-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"
* Permissions for groups apply when the user is member of that group.
* Permissions replace the ones inherited from an upper level.
+Additionally, privilege separated tokens can never have a permission on any
+given path that their associated user does not have.
[[pveum_pools]]
Pools
`["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
-----------------
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
-function through the REST API.
+functions through the REST API.
Here are some simple usage examples. To show help type:
NOTE: The user is able to add other users, but only if they are
members of group `customers` and within realm `pve`.
+Limited API token for monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
+
+[source,bash]
+ pveum aclmod /vms -user joe@pve -role PVEVMAdmin
+
+Add a new API token with separate privileges, which is only allowed to view VM
+information (e.g., for monitoring purposes):
+
+[source,bash]
+ pveum user token add joe@pve monitoring -privsep 1
+ pveum aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor
+
+Verify the permissions of the user and token:
+
+[source,bash]
+ pveum user permissions joe@pve
+ pveum user token permissions joe@pve monitoring
Pools
~~~~~
projects / pve-docs.git / blobdiff