X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=1447d3832b04b23459f2ea0a7a68665a0b837139;hp=8c187c01410363bea8282cfadce6bef7c610faa4;hb=2837cf1d93d0ca99e18edfd72ada0b966f5268a8;hpb=5462c16110abe799ec52a894924ec894aacce917 diff --git a/pveum.adoc b/pveum.adoc index 8c187c0..1447d38 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -1,7 +1,8 @@ +[[chapter_user_management]] ifdef::manvolnum[] -PVE({manvolnum}) -================ -include::attributes.txt[] +pveum(1) +======== +:pve-toplevel: NAME ---- @@ -9,7 +10,7 @@ NAME pveum - Proxmox VE User Manager -SYNOPSYS +SYNOPSIS -------- include::pveum.1-synopsis.adoc[] @@ -18,11 +19,10 @@ include::pveum.1-synopsis.adoc[] DESCRIPTION ----------- endif::manvolnum[] - ifndef::manvolnum[] User Management =============== -include::attributes.txt[] +:pve-toplevel: endif::manvolnum[] // Copied from pve wiki: Revision as of 16:10, 27 October 2015 @@ -35,7 +35,48 @@ By using the role based user- and permission management for all objects (VMs, storages, nodes, etc.) granular access can be defined. -[[authentication-realms]] +[[pveum_users]] +Users +----- + +{pve} stores user attributes in `/etc/pve/user.cfg`. +Passwords are not stored here, users are instead associated with +<> described below. +Therefore a user is internally often identified by its name and +realm in the form `@`. + +Each user entry in this file contains the following information: + +* First name +* Last name +* E-mail address +* Group memberships +* An optional Expiration date +* A comment or note about this user +* Whether this user is enabled or disabled +* Optional two factor authentication keys + + +System administrator +~~~~~~~~~~~~~~~~~~~~ + +The system's root user can always log in via the Linux PAM realm and is an +unconfined administrator. This user cannot be deleted, but attributes can +still be changed and system mails will be sent to the email address +assigned to this user. + + +[[pveum_groups]] +Groups +~~~~~~ + +Each user can be member of several groups. Groups are the preferred +way to organize access permissions. You should always grant permission +to groups instead of using individual users. That way you will get a +much shorter access control list which is easier to handle. + + +[[pveum_authentication_realms]] Authentication Realms --------------------- @@ -44,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. + @@ -59,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. + @@ -96,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:: @@ -109,8 +150,23 @@ encryption can be configured. 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. @@ -143,52 +199,120 @@ 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]. +User configured TOTP authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Terms and Definitions ---------------------- +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. -Users -~~~~~ +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. -A Proxmox VE user name consists of two parts: `@`. The -login screen on the GUI shows them a separate items, but it is -internally used as single string. +Server side U2F configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We store the following attribute for users (`/etc/pve/user.cfg`): +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. -* first name -* last name -* email address -* expiration date -* flag to enable/disable account -* comment +NOTE: Changing the 'AppId' will render all existing 'U2F' registrations +unusable! +This is done via `/etc/pve/datacenter.cfg`, for instance: -Superuser -^^^^^^^^^ +---- +u2f: appid=https://mypve.example.com:8006 +---- -The traditional unix superuser account is called `root@pam`. All -system mails are forwarded to the email assigned to that account. +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). -Groups -~~~~~~ +Firefox users may need to enable 'security.webauth.u2f' via 'about:config' +before they can use a 'U2F' token. -Each user can be member of several groups. Groups are the preferred -way to organize access permissions. You should always grant permission -to groups instead of using individual users. That way you will get a -much shorter access control list which is easier to handle. +[[pveum_permission_management]] +Permission Management +--------------------- +In order for a user to perform an action (such as listing, modifying or +deleting a parts of a VM configuration), the user needs to have the +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 +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. -Objects and Paths -~~~~~~~~~~~~~~~~~ -Access permissions are assigned to objects, such as a virtual machines -(`/vms/{vmid}`) or a storage (`/storage/{storeid}`) or a pool of -resources (`/pool/{poolname}`). We use file system like paths to -address those objects. Those paths form a natural tree, and -permissions can be inherited down that hierarchy. +[[pveum_roles]] +Roles +~~~~~ + +A role is simply a list of privileges. Proxmox VE comes with a number +of predefined roles which satisfies most needs. + +* `Administrator`: has all privileges +* `NoAccess`: has no privileges (used to forbid access) +* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). +* `PVEAuditor`: read only access +* `PVEDatastoreAdmin`: create and allocate backup space and templates +* `PVEDatastoreUser`: allocate backup space and view storage +* `PVEPoolAdmin`: allocate pools +* `PVESysAdmin`: User ACLs, audit, system console and system logs +* `PVETemplateUser`: view and clone templates +* `PVEUserAdmin`: user administration +* `PVEVMAdmin`: fully administer VMs +* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management + +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: + +[source,bash] +---- +pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" +pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" +---- Privileges @@ -196,7 +320,8 @@ Privileges A privilege is the right to perform a specific action. To simplify management, lists of privileges are grouped into roles, which can then -be uses to set permissions. +be used in the permission table. Note that privileges cannot directly be +assigned to users and paths without being part of a role. We currently use the following privileges: @@ -206,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.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 @@ -241,48 +366,33 @@ Storage related privileges:: * `Datastore.Audit`: view/browse a datastore -Roles -~~~~~ - -A role is simply a list of privileges. Proxmox VE comes with a number -of predefined roles which satisfies most needs. - -* `Administrator`: has all privileges -* `NoAccess`: has no privileges (used to forbid access) -* `PVEAdmin`: can do most things, but miss rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`). -* `PVEAuditor`: read only access -* `PVEDatastoreAdmin`: create and allocate backup space and templates -* `PVEDatastoreUser`: allocate backup space and view storage -* `PVEPoolAdmin`: allocate pools -* `PVESysAdmin`: User ACLs, audit, system console and system logs -* `PVETemplateUser`: view and clone templates -* `PVEUserAdmin`: user administration -* `PVEVMAdmin`: fully administer VMs -* `PVEVMUser`: view, backup, config CDROM, VM console, VM power management - -You can see the whole set of predefined roles on the GUI. - -Adding new roles using the CLI: - -[source,bash] ----- -pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" -pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" ----- +Objects and Paths +~~~~~~~~~~~~~~~~~ +Access permissions are assigned to objects, such as a virtual machines, +storages or pools of resources. +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. -Permissions -~~~~~~~~~~~ +[[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 +implicitly taken from the API call's URI. For instance the permission path +`/nodes/{node}` when calling '/nodes/mynode/status' requires permissions on +`/nodes/mynode`, while the path `{path}` in a PUT request to `/access/acl` +refers to the method's `path` parameter. -Permissions are the way we control access to objects. In technical -terms they are simply a triple containing ``. This -concept is also known as access control lists. Each permission -specifies a subject (user or group) and a role (set of privileges) on -a specific path. +Some examples are: -When a subject requests an action on an object, the framework looks up -the roles assigned to that subject (using the object path). The set of -roles defines the granted privileges. +* `/nodes/{node}`: Access to {pve} server machines +* `/vms`: Covers all VMs +* `/vms/{vmid}`: Access to specific VMs +* `/storage/{storeid}`: Access to a storages +* `/pool/{poolname}`: Access to VMs part of a <> +* `/access/groups`: Group administration +* `/access/realms/{realmid}`: Administrative access to realms Inheritance @@ -297,6 +407,7 @@ by default). We use the following inheritance rules: * Permissions replace the ones inherited from an upper level. +[[pveum_pools]] Pools ~~~~~ @@ -319,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", , [ ... ], ...]`:: -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: + @@ -345,14 +457,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` @@ -452,7 +565,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]