// 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 (VMs, storages, nodes, etc.) granular access can be defined.
+Users
+-----
+
+{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>`.
+
+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.
+
+
+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
---------------------
encryption can be configured.
-Terms and Definitions
----------------------
-
-
-Users
-~~~~~
-
-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.
-
-We store the following attribute for users (`/etc/pve/user.cfg`):
+Two factor authentication
+-------------------------
-* first name
-* last name
-* email address
-* expiration date
-* flag to enable/disable account
-* comment
+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:
-Superuser
-^^^^^^^^^
-
-The traditional unix superuser account is called `root@pam`. All
-system mails are forwarded to the email assigned to that account.
-
+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].
-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.
+Terms and Definitions
+---------------------
Objects and Paths
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.
-
-
-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/
+* 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.
Pools
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
-----------------
projects / pve-docs.git / blobdiff