From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id CA754648ED for ; Fri, 30 Oct 2020 15:18:51 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C823614D51 for ; Fri, 30 Oct 2020 15:18:51 +0100 (CET) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 0C64E14D47 for ; Fri, 30 Oct 2020 15:18:51 +0100 (CET) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id CBD8345F90 for ; Fri, 30 Oct 2020 15:18:50 +0100 (CET) From: =?UTF-8?q?Fabian=20Gr=C3=BCnbichler?= To: pbs-devel@lists.proxmox.com Date: Fri, 30 Oct 2020 15:18:42 +0100 Message-Id: <20201030141842.1024730-2-f.gruenbichler@proxmox.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20201030141842.1024730-1-f.gruenbichler@proxmox.com> References: <20201030141842.1024730-1-f.gruenbichler@proxmox.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL 0.026 Adjusted score from AWL reputation of From: address KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [datastore.read] Subject: [pbs-devel] [PATCH proxmox-backup 2/2] docs: add API tokens to documentation X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 30 Oct 2020 14:18:51 -0000 Signed-off-by: Fabian Grünbichler --- docs/user-management.rst | 116 ++++++++++++++++++++++++++++++++++----- 1 file changed, 103 insertions(+), 13 deletions(-) diff --git a/docs/user-management.rst b/docs/user-management.rst index 56ad7a71..3b629780 100644 --- a/docs/user-management.rst +++ b/docs/user-management.rst @@ -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 (*) -- 2.20.1