// 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
+<<authentication-realms,authentication realms>> described below.
+Therefore a user is internally often identified by its name and
+realm in the form `<userid>@<realm>`.
-LDAP::
+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
-Linux PAM standard authentication::
-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!
+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
+~~~~~~
+
+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
----
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.
-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.
+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/<realmname>.pw`
+(eg. `/etc/pve/priv/ldap/my-ldap.pw`). This file should contain a
+single line containing the raw password.
+
+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: `<userid>@<realm>`. 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
~~~~~~~~~~~~~~~~~
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 filesystem like paths to
+(`/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.
+
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
~~~~~~~~~~~
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/pve2-api-doc/
Pools
~~~~~
Pools can be used to group a set of virtual machines and data
-stores. You can then simply set permissions on pools ('/pool/{poolid}'),
+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", <subtests>...]` and `["or", <subtests>...]`::
+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 <<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
+API call's schema otherwise lists it as being optional.
+
+`["userid-group", [ <privileges>... ], <options>...]`::
+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/<group>` 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/<realm>`, with
+`<realm>` 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
+`<username>@<realm>`.
+
+`["perm-modify", <path>]`::
+The `path` is a templated parameter (see <<templated-paths,Objects and
+Paths>>). 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 'Proxmox
-VE User Manager'). 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.
+a full 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.
Here are some simple usage examples. To show help type:
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:
You can give read only access to users by assigning the `PVEAuditor`
role to users or groups.
-Example1: Allow user 'joe@pve' to see everything
+Example1: Allow user `joe@pve` to see everything
[source,bash]
pveum aclmod / -user joe@pve -role PVEAuditor
-Example1: Allow user 'joe@pve' to see all virtual machines
+Example1: Allow user `joe@pve` to see all virtual machines
[source,bash]
pveum aclmod /vms -user joe@pve -role PVEAuditor
+
Delegate User Management
~~~~~~~~~~~~~~~~~~~~~~~~
-If you want to delegate user managenent to user 'joe@pve' you can do
+If you want to delegate user managenent to user `joe@pve` you can do
that with:
[source,bash]
pveum aclmod /access -user joe@pve -role PVEUserAdmin
-User 'joe@pve' can now add and remove users, change passwords and
+User `joe@pve` can now add and remove users, change passwords and
other user attributes. This is a very powerful role, and you most
likely want to limit that to selected realms and groups. The following
-example allows 'joe@pve' to modify users within realm 'pve' if they
-are members of group 'customers':
+example allows `joe@pve` to modify users within realm `pve` if they
+are members of group `customers`:
[source,bash]
pveum aclmod /access/realm/pve -user joe@pve -role PVEUserAdmin
pveum aclmod /access/groups/customers -user joe@pve -role PVEUserAdmin
-Note: The user is able to add other users, but only if they are
-members of group 'customers' and within realm 'pve'.
+NOTE: The user is able to add other users, but only if they are
+members of group `customers` and within realm `pve`.
+
Pools
~~~~~
[source,bash]
pveum useradd developer1@pve -group developers -password
-Note: The -password parameter will prompt you for a password
+NOTE: The -password parameter will prompt you for a password
-I assume we already created a pool called 'dev-pool' on the GUI. So we can now assign permission to that pool:
+I assume we already created a pool called ``dev-pool'' on the GUI. So we can now assign permission to that pool:
[source,bash]
pveum aclmod /pool/dev-pool/ -group developers -role PVEAdmin
projects / pve-docs.git / blobdiff