[pve-devel] [PATCH docs 1/2] document API tokens

[Fabian Grünbichler]

Signed-off-by: Fabian Grünbichler <f.gruenbichler at 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 at 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 at pve` with PVEVMAdmin role on all vms:
+
+[source,bash]
+ pveum aclmod /vms -user joe at 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 at pve monitoring -privsep 1
+ pveum aclmod /vms -token 'joe at pve!monitoring' -role PVEAuditor
+
+Verify permissions of user and token:
+
+[source,bash]
+ pveum user permissions joe at pve
+ pveum user token permissions joe at pve monitoring
 
 Pools
 ~~~~~
-- 
2.20.1