X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=59a28245c0b53003ed521dab9a02b2c2d12d77cc;hp=95406c9874282224acd33e3583501b69a1df71e7;hb=b03b8bb6c3a1470c79add026fd782907d69a2d6e;hpb=194d2f296102b7693c5915ff803e225f6d3b6526 diff --git a/pveum.adoc b/pveum.adoc index 95406c9..59a2824 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -2,7 +2,6 @@ ifdef::manvolnum[] pveum(1) ======== -include::attributes.txt[] :pve-toplevel: NAME @@ -23,7 +22,6 @@ endif::manvolnum[] ifndef::manvolnum[] User Management =============== -include::attributes.txt[] :pve-toplevel: endif::manvolnum[] @@ -56,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 -* Optional two factor authentication keys +* Optional two-factor authentication keys System administrator @@ -87,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:: -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. + @@ -102,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. -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:: -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. + @@ -139,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/.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:: @@ -149,29 +147,45 @@ ldap an optional fallback server, optional port, and SSL 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 @@ -179,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. + + -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 @@ -225,9 +312,15 @@ of predefined roles which satisfies most needs. 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" @@ -251,7 +344,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.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 @@ -295,7 +388,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. -[[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 @@ -310,7 +403,7 @@ Some examples are: * `/vms`: Covers all VMs * `/vms/{vmid}`: Access to specific VMs * `/storage/{storeid}`: Access to a storages -* `/pool/{poolname}`: Access to VMs part of a < +* `/pool/{poolname}`: Access to VMs part of a <> * `/access/groups`: Group administration * `/access/realms/{realmid}`: Administrative access to realms @@ -350,14 +443,15 @@ tree of logic and access-check functions: Each(`and`) or any(`or`) further element in the current list has to be true. `["perm", , [ ... ], ...]`:: -The `path` is a templated parameter (see <>). All (or , if the `any` option is used, any) of the listed +The `path` is a templated parameter (see +<>). 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", [ ... ], ...]`:: -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: + @@ -376,14 +470,15 @@ privileges.) `["userid-param", "Realm.AllocateUser"]`:: The user needs `Realm.AllocateUser` access to `/access/realm/`, with -`` refering to the realm of the user passed via the `userid` +`` 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 `@`. `["perm-modify", ]`:: -The `path` is a templated parameter (see <>). The user needs either the `Permissions.Modify` privilege, or, +The `path` is a templated parameter (see +<>). 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` @@ -396,10 +491,10 @@ Command Line Tool ----------------- 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: @@ -483,7 +578,7 @@ Example1: Allow user `joe@pve` to see all virtual machines 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]