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

[Aaron Lauterer]

Inline suggestions for restructuring some paragraphs for an easier 
understanding and some other small things.
I hope I didn't lose information in the restructured paragraphs.

On 1/30/20 1:54 PM, Fabian Grünbichler wrote:
> 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 allow stateless access to most parts of the REST API for 
another system, software or API client. They 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: token needs to be given explicit access with ACLs,
s/token/The token/
s/ACLs,/ACLs./

> +  effective permissions are calculated by intersecting user and token
s/effective/The effective/
s/user/the user/
> +  permissions
s/permissions/permissions./

> +* full privileges: token permissions are automatically identical to that of the
> +  associated user
s/token/The token/
s/automatically// #I think this could be removed and the sentence still 
works.
s/user/user./

> +
> +WARNING: the token value is only displayed/returned once when initially generating
> +the token, and not retrievable over the API later on!
WARNING: The token value is only displayed/returned *once* when the 
token is generated. It cannot be retrieved over the API at a later time!

> +
> +To use an API token, simple set the HTTP header 'Authorization' to the
s/simple//

> +displayed value of the form `PVEAPIToken=USER at REALM!TOKENID=UUID` when making
s/of/in/
s/form/form of/

Would it make sense to set the example to 
`PVEAPIToken=<user>@<realm>!TOKENID=<Token UUID>` or some other 
placeholder that will make it more obvious where data needs to be inserted?

Is the header really mixed in regards to Capitalization?

> +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:
s/with/with the/
s/vms/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:
s/permissions/the permissions/
s/user/the user/
> +
> +[source,bash]
> + pveum user permissions joe at pve
> + pveum user token permissions joe at pve monitoring
>   
>   Pools
>   ~~~~~
>