Signed-off-by: Fabian Grünbichler <f.gruenbich...@proxmox.com>
---
Note: we don't yet have a basic 'intro to REST API' section in the user
docs. it might make sense to copy some of the related wiki content,
explain the ticketing mechanism, etc.pp.
pveum.adoc | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 50 insertions(+), 3 deletions(-)
diff --git a/pveum.adoc b/pveum.adoc
index 59a2824..cf5f70b 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -75,6 +75,31 @@ 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
+~~~~~~~~~~
+
+For situations where giving a system/software/API client permanent access to a
+{pve} system is required, API tokens can be generated for individual users.
+These tokens allow stateless access to most of the REST API, and can be given
+separate permissions and expiry dates to limit the scope and duration of
+access. In case an API token was compromised, it can be revoked without
+disabling the whole user.
+
+API tokens come in two basic types:
+
+* separated privileges: token needs to be given explicit access with ACLs,
+ effective permissions are calculated by intersecting user and token
+ permissions
+* full privileges: token permissions are automatically identical to that of the
+ associated user
+
+WARNING: the token value is only displayed/returned once when initially
generating
+the token, and not retrievable over the API later on!
+
+To use an API token, simple 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
@@ -283,10 +308,10 @@ 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
+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
+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.
@@ -419,6 +444,8 @@ by default). We use the following inheritance rules:
* 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
@@ -597,6 +624,26 @@ are members of group `customers`:
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 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 permissions of user and token:
+
+[source,bash]
+ pveum user permissions joe@pve
+ pveum user token permissions joe@pve monitoring
Pools
~~~~~
--
2.20.1
_______________________________________________
pve-devel mailing list
pve-devel@pve.proxmox.com
https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
