X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=blobdiff_plain;f=pveum.adoc;h=f1abd942dfdbe669e77dbe51a4686f4805abdca3;hp=f68b243cf4962bc7700fb52509564b413448ae74;hb=853d288bd5ae906fc99b3008d37ba81e8951dd08;hpb=8c1189b640ae7d10119ff1c046580f48749d38bd diff --git a/pveum.adoc b/pveum.adoc index f68b243..f1abd94 100644 --- a/pveum.adoc +++ b/pveum.adoc @@ -27,31 +27,66 @@ endif::manvolnum[] // Copied from pve wiki: Revision as of 16:10, 27 October 2015 -Proxmox VE supports multiple authentication sources, e.g. Microsoft -Active Directory, LDAP, Linux PAM or the integrated Proxmox VE -authentication server. +Proxmox VE supports multiple authentication sources, e.g. Linux PAM, +an integrated Proxmox VE authentication server, LDAP, Microsoft Active +Directory. By using the role based user- and permission management for all -objects (VM´s, storages, nodes, etc.) granular access can be defined. +objects (VMs, storages, nodes, etc.) granular access can be defined. -Authentication Realms ---------------------- -Proxmox VE stores all user attributes in `/etc/pve/user.cfg`. So there -must be an entry for each user in that file. The password is not -stored, instead you can use configure several realms to verify -passwords. +Users +----- -Microsoft Active Directory:: +{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 `@`. -LDAP:: +Each user entry in this file contains the following information: -Linux PAM standard authentication:: +* 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. + + +Groups +~~~~~~ -You need to create the system users first with `adduser` -(e.g. `adduser heinz`) and possibly the group as well. After that you -can create the user on the GUI. +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. + +[[authentication-realms]] +Authentication Realms +--------------------- + +As {pve} users are just counterparts for users existing on some external +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` +command) on all nodes the user is allowed to login, and the user +authenticates with their usual system password. ++ [source,bash] ---- useradd heinz @@ -61,43 +96,138 @@ 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) +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. +openldap). The server and an optional fallback server can be +configured and the connection can be encrypted via SSL. ++ +Users are searched under a 'Base Domain Name' (`base_dn`), with the +user name found in the attribute specified in the 'User Attribute Name' +(`user_attr`) field. ++ +For instance, if a user is represented via the +following ldif dataset: ++ +---- +# user1 of People at ldap-test.com +dn: uid=user1,ou=People,dc=ldap-test,dc=com +objectClass: top +objectClass: person +objectClass: organizationalPerson +objectClass: inetOrgPerson +uid: user1 +cn: Test User 1 +sn: Testers +description: This is the first test user. +---- ++ +The 'Base Domain Name' would be `ou=People,dc=ldap-test,dc=com` and the user +attribute would be `uid`. ++ +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 +single line containing the raw password. -This is a unix like password store -(`/etc/pve/priv/shadow.cfg`). Password are encrypted using the SHA-256 -hash method. Users are allowed to change passwords. +Microsoft Active Directory:: -Terms and Definitions +A server and authentication domain need to be specified. Like with +ldap an optional fallback server, optional port, and SSL +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 +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. ++ +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. + +YubiKey OTP:: +For authenticating via a YubiKey a Yubico API ID, API KEY and validation +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 +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]. + + +Permission Management --------------------- -Users -~~~~~ +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. -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. +{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. -We store the following attribute for users (`/etc/pve/user.cfg`): -* first name -* last name -* email address -* expiration date -* flag to enable/disable account -* comment +Roles +~~~~~ -Superuser -^^^^^^^^^ +A role is simply a list of privileges. Proxmox VE comes with a number +of predefined roles which satisfies most needs. -The traditional unix superuser account is called `root@pam`. All -system mails are forwarded to the email assigned to that account. +* `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 -Groups -~~~~~~ +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: + +[source,bash] +---- +pveum roleadd PVE_Power-only -privs "VM.PowerMgmt VM.Console" +pveum roleadd Sys_Power-only -privs "Sys.PowerMgmt Sys.Console" +---- -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. Objects and Paths ~~~~~~~~~~~~~~~~~ @@ -108,6 +238,7 @@ 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. + Privileges ~~~~~~~~~~ @@ -157,35 +288,6 @@ Storage related privileges:: * `Datastore.AllocateTemplate`: allocate/upload templates and iso images * `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" ----- - Permissions ~~~~~~~~~~~ @@ -200,22 +302,18 @@ 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. + Inheritance ^^^^^^^^^^^ -As mentioned earlier, object paths forms a filesystem like tree, and +As mentioned earlier, object paths form a file system like tree, and permissions can be inherited down that tree (the propagate flag is set by default). We use the following inheritance rules: -* permission for individual users always overwrite group permission. -* permission for groups apply when the user is member of that group. -* permission set at higher level always overwrites inherited permissions. +* Permissions for individual users always replace group permissions. +* Permissions for groups apply when the user is member of that group. +* Permissions replace the ones inherited from an upper level. -What permission do I need? -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The required API permissions are documented for each individual -method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ Pools ~~~~~ @@ -225,15 +323,70 @@ stores. You can then simply set permissions on pools (`/pool/{poolid}`), which are inherited to all pool members. This is a great way simplify access control. + +What permission do I need? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The required API permissions are documented for each individual +method, and can be found at http://pve.proxmox.com/pve-docs/api-viewer/ + +The permissions are specified as a list which can be interpreted as a +tree of logic and access-check functions: + +`["and", ...]` and `["or", ...]`:: +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 +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 +addition there are two possible checks depending on whether the +`groups_param` option is set: ++ +* `groups_param` is set: The API call has a non-optional `groups` parameter +and the caller must have any of the listed privileges on all of the listed +groups. +* `groups_param` is not set: The user passed via the `userid` parameter +must exist and be part of a group on which the caller has any of the listed +privileges (via the `/access/groups/` path). + +`["userid-param", "self"]`:: +The value provided for the API call's `userid` parameter must refer to the +user performing the action. (Usually in conjunction with `or`, to allow +users to perform an action on themselves even if they don't have elevated +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` +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, +depending on the path, the following privileges as a possible substitute: ++ +* `/storage/...`: additionally requires 'Datastore.Allocate` +* `/vms/...`: additionally requires 'VM.Allocate` +* `/pool/...`: additionally requires 'Pool.Allocate` ++ +If the path is empty, `Permission.Modify` on `/access` is required. + 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 -**VE** **U**ser **M**anager''). I will use that tool in the following -examples. 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. +**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. Here are some simple usage examples. To show help type: @@ -274,11 +427,12 @@ Create a new role: Real World Examples ------------------- + Administrator Group ~~~~~~~~~~~~~~~~~~~ One of the most wanted features was the ability to define a group of -users with full administartor rights (without using the root account). +users with full administrator rights (without using the root account). Define the group: @@ -312,6 +466,7 @@ Example1: Allow user `joe@pve` to see all virtual machines [source,bash] pveum aclmod /vms -user joe@pve -role PVEAuditor + Delegate User Management ~~~~~~~~~~~~~~~~~~~~~~~~