[[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_tokens]]
+API Tokens
+----------
+
+API tokens allow stateless access to most parts of the REST API by another
+system, software or API client. Tokens can be generated for individual users
+and can be given separate permissions and expiration dates to limit the scope
+and duration of the access. Should the API token get compromised it can be
+revoked without disabling the user itself.
+
+API tokens come in two basic types:
+
+* separated privileges: the token needs to be given explicit access with ACLs,
+ its effective permissions are calculated by intersecting user and token
+ permissions.
+* full privileges: the token permissions are identical to that of the
+ associated user.
+
+CAUTION: The token value is only displayed/returned once when the token is
+generated. It cannot be retrieved again over the API at a later time!
+
+To use an API token, set the HTTP header 'Authorization' to the displayed value
+of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
+refer to your API client documentation.
[[pveum_authentication_realms]]
Authentication Realms
ldap an optional fallback server, optional port, and SSL
encryption can be configured.
+[[pveum_ldap_sync]]
+Syncing LDAP-based realms
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap.png"]
+
+It is possible to sync users and groups for LDAP based realms. You can use the
+CLI command
+
+----
+ pveum realm sync <realm>
+----
+or in the `Authentication` panel of the GUI. Users and groups are synced to the
+cluster-wide user configuration file `/etc/pve/user.cfg`.
+
+Requirements and limitations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `bind_dn` is used to query the users and groups. This account needs access
+to all desired entries.
+
+The fields which represent the names of the users and groups can be configured
+via the `user_attr` and `group_name_attr` respectively. Only entries which
+adhere to the usual character limitations of the user.cfg are synced.
+
+Groups are synced with `-$realm` attached to the name, to avoid naming
+conflicts. Please make sure that a sync does not overwrite manually created
+groups.
+
+[[pveum_ldap_sync_options]]
+Options
+^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-realm-add-ldap-sync-options.png"]
+
+The main options for syncing are:
+
+* `dry-run`: No data is written to the config. This is useful if you want to
+ see which users and groups would get synced to the user.cfg. This is set
+ when you click `Preview` in the GUI.
+
+* `enable-new`: If set, the newly synced users are enabled and can login.
+ The default is `true`.
+
+* `full`: If set, the sync uses the LDAP Directory as a source of truth,
+ overwriting information set manually in the user.cfg and deletes users
+ and groups which are not present in the LDAP directory. If not set,
+ only new data is written to the config, and no stale users are deleted.
+
+* `purge`: If set, sync removes all corresponding ACLs when removing users
+ and groups. This is only useful with the option `full`.
+
+* `scope`: The scope of what to sync. It can be either `users`, `groups` or
+ `both`.
+
+These options are either set as parameters or as defaults, via the
+realm option `sync-defaults-options`.
[[pveum_tfa_auth]]
Two-factor authentication
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
+https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host
your own verification server].
[[pveum_user_configured_totp]]
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
+the permissions table allows a user, group or token 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.
+be represented as a triple of '(path, user, role)', '(path, group,
+role)' or '(path, token, role)', with the role containing a set of allowed
+actions, and the path representing the target of these actions.
[[pveum_roles]]
* Permissions for groups apply when the user is member of that group.
* Permissions replace the ones inherited from an upper level.
+Additionally, privilege separated tokens can never have a permission on any
+given path that their associated user does not have.
[[pveum_pools]]
Pools
NOTE: The user is able to add other users, but only if they are
members of group `customers` and within realm `pve`.
+Limited API token for monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given a user `joe@pve` with the PVEVMAdmin role on all VMs:
+
+[source,bash]
+ pveum aclmod /vms -user joe@pve -role PVEVMAdmin
+
+Add a new API token with separate privileges, which is only allowed to view VM
+information (e.g., for monitoring purposes):
+
+[source,bash]
+ pveum user token add joe@pve monitoring -privsep 1
+ pveum aclmod /vms -token 'joe@pve!monitoring' -role PVEAuditor
+
+Verify the permissions of the user and token:
+
+[source,bash]
+ pveum user permissions joe@pve
+ pveum user token permissions joe@pve monitoring
Pools
~~~~~
projects / pve-docs.git / blobdiff