docs: add API tokens to documentation
Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>
This commit is contained in:
Fabian Grünbichler
committed by
Thomas Lamprecht
Thomas Lamprecht
parent
8b600f9965
commit
034cf70b72
@ -70,7 +70,7 @@ The resulting user list looks like this:
|
||||
│ root@pam │ 1 │ │ │ │ │ Superuser │
|
||||
└──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘
|
||||
|
||||
Newly created users do not have any permissions. Please read the next
|
||||
Newly created users do not have any permissions. Please read the Access Control
|
||||
section to learn how to set access permissions.
|
||||
|
||||
If you want to disable a user account, you can do that by setting ``--enable`` to ``0``
|
||||
@ -85,15 +85,69 @@ Or completely remove the user with:
|
||||
|
||||
# proxmox-backup-manager user remove john@pbs
|
||||
|
||||
.. _user_tokens:
|
||||
|
||||
API Tokens
|
||||
----------
|
||||
|
||||
Any authenticated user can generate API tokens which can in turn be used to
|
||||
configure various clients, instead of directly providing the username and
|
||||
password.
|
||||
|
||||
API tokens serve two purposes:
|
||||
|
||||
#. Easy revocation in case client gets compromised
|
||||
#. Limit permissions for each client/token within the users' permission
|
||||
|
||||
An API token consists of two parts: an identifier consisting of the user name,
|
||||
the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both
|
||||
need to be provided to the client in place of the user ID (``user@realm``) and
|
||||
the user password.
|
||||
|
||||
The API token is passed from the client to the server by setting the
|
||||
``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
|
||||
``TOKENID:TOKENSECRET``.
|
||||
|
||||
Generating new tokens can done using ``proxmox-backup-manager`` or the GUI:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager user generate-token john@pbs client1
|
||||
Result: {
|
||||
"tokenid": "john@pbs!client1",
|
||||
"value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde"
|
||||
}
|
||||
|
||||
.. note:: The displayed secret value needs to be saved, since it cannot be
|
||||
displayed again after generating the API token.
|
||||
|
||||
The ``user list-tokens`` sub-command can be used to display tokens and their
|
||||
metadata:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager user list-tokens john@pbs
|
||||
┌──────────────────┬────────┬────────┬─────────┐
|
||||
│ tokenid │ enable │ expire │ comment │
|
||||
╞══════════════════╪════════╪════════╪═════════╡
|
||||
│ john@pbs!client1 │ 1 │ │ │
|
||||
└──────────────────┴────────┴────────┴─────────┘
|
||||
|
||||
Similarly, the ``user delete-token`` subcommand can be used to delete a token
|
||||
again.
|
||||
|
||||
Newly generated API tokens don't have any permissions. Please read the next
|
||||
section to learn how to set access permissions.
|
||||
|
||||
|
||||
.. _user_acl:
|
||||
|
||||
Access Control
|
||||
--------------
|
||||
|
||||
By default new users do not have any permission. Instead you need to
|
||||
specify what is allowed and what is not. You can do this by assigning
|
||||
roles to users on specific objects like datastores or remotes. The
|
||||
By default new users and API tokens do not have any permission. Instead you
|
||||
need to specify what is allowed and what is not. You can do this by assigning
|
||||
roles to users/tokens on specific objects like datastores or remotes. The
|
||||
following roles exist:
|
||||
|
||||
**NoAccess**
|
||||
@ -148,20 +202,21 @@ The data represented in each field is as follows:
|
||||
#. The object on which the permission is set. This can be a specific object
|
||||
(single datastore, remote, etc.) or a top level object, which with
|
||||
propagation enabled, represents all children of the object also.
|
||||
#. The user for which the permission is set
|
||||
#. The user(s)/token(s) for which the permission is set
|
||||
#. The role being set
|
||||
|
||||
You can manage datastore permissions from **Configuration -> Permissions** in the
|
||||
web interface. Likewise, you can use the ``acl`` subcommand to manage and
|
||||
monitor user permissions from the command line. For example, the command below
|
||||
will add the user ``john@pbs`` as a **DatastoreAdmin** for the datastore
|
||||
``store1``, located at ``/backup/disk1/store1``:
|
||||
You can manage permissions via **Configuration -> Access Control ->
|
||||
Permissions** in the web interface. Likewise, you can use the ``acl``
|
||||
subcommand to manage and monitor user permissions from the command line. For
|
||||
example, the command below will add the user ``john@pbs`` as a
|
||||
**DatastoreAdmin** for the datastore ``store1``, located at
|
||||
``/backup/disk1/store1``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --userid john@pbs
|
||||
# proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs
|
||||
|
||||
You can monitor the roles of each user using the following command:
|
||||
You can list the ACLs of each user/token using the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -172,7 +227,7 @@ You can monitor the roles of each user using the following command:
|
||||
│ john@pbs │ /datastore/disk1 │ 1 │ DatastoreAdmin │
|
||||
└──────────┴──────────────────┴───────────┴────────────────┘
|
||||
|
||||
A single user can be assigned multiple permission sets for different datastores.
|
||||
A single user/token can be assigned multiple permission sets for different datastores.
|
||||
|
||||
.. Note::
|
||||
Naming convention is important here. For datastores on the host,
|
||||
@ -183,4 +238,39 @@ A single user can be assigned multiple permission sets for different datastores.
|
||||
remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
|
||||
the remote.
|
||||
|
||||
API Token permissions
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
API token permissions are calculated based on ACLs containing their ID
|
||||
independent of those of their corresponding user. The resulting permission set
|
||||
on a given path is then intersected with that of the corresponding user.
|
||||
|
||||
In practice this means:
|
||||
|
||||
#. API tokens require their own ACL entries
|
||||
#. API tokens can never do more than their corresponding user
|
||||
|
||||
Effective permissions
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To calculate and display the effective permission set of a user or API token
|
||||
you can use the ``proxmox-backup-manager user permission`` command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# proxmox-backup-manager user permissions john@pbs -- path /datastore/store1
|
||||
Privileges with (*) have the propagate flag set
|
||||
|
||||
Path: /datastore/store1
|
||||
- Datastore.Audit (*)
|
||||
- Datastore.Backup (*)
|
||||
- Datastore.Modify (*)
|
||||
- Datastore.Prune (*)
|
||||
- Datastore.Read (*)
|
||||
|
||||
# proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
|
||||
# proxmox-backup-manager user permissions 'john@pbs!test' -- path /datastore/store1
|
||||
Privileges with (*) have the propagate flag set
|
||||
|
||||
Path: /datastore/store1
|
||||
- Datastore.Backup (*)
|
||||
|
||||
Reference in New Issue
Block a user