* [pbs-devel] [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id
@ 2020-10-30 14:18 Fabian Grünbichler
2020-10-30 14:18 ` [pbs-devel] [PATCH proxmox-backup 2/2] docs: add API tokens to documentation Fabian Grünbichler
2020-10-30 16:02 ` [pbs-devel] applied: [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id Thomas Lamprecht
0 siblings, 2 replies; 4+ messages in thread
From: Fabian Grünbichler @ 2020-10-30 14:18 UTC (permalink / raw)
To: pbs-devel
in parameters, and fix up the completion for the ACL update parameter.
Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>
---
src/api2/access.rs | 2 +-
src/api2/access/acl.rs | 2 +-
src/bin/proxmox_backup_manager/acl.rs | 2 +-
src/bin/proxmox_backup_manager/user.rs | 6 +++---
www/config/ACLView.js | 2 +-
www/config/TokenView.js | 2 +-
www/config/UserView.js | 2 +-
www/window/ACLEdit.js | 4 ++--
8 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/src/api2/access.rs b/src/api2/access.rs
index 5e74a6ee..9b9e85c0 100644
--- a/src/api2/access.rs
+++ b/src/api2/access.rs
@@ -244,7 +244,7 @@ fn change_password(
#[api(
input: {
properties: {
- auth_id: {
+ "auth-id": {
type: Authid,
optional: true,
},
diff --git a/src/api2/access/acl.rs b/src/api2/access/acl.rs
index a776ceaa..ff9da466 100644
--- a/src/api2/access/acl.rs
+++ b/src/api2/access/acl.rs
@@ -169,7 +169,7 @@ pub fn read_acl(
optional: true,
schema: ACL_PROPAGATE_SCHEMA,
},
- auth_id: {
+ "auth-id": {
optional: true,
type: Authid,
},
diff --git a/src/bin/proxmox_backup_manager/acl.rs b/src/bin/proxmox_backup_manager/acl.rs
index 3fbb3bcb..7511c8cb 100644
--- a/src/bin/proxmox_backup_manager/acl.rs
+++ b/src/bin/proxmox_backup_manager/acl.rs
@@ -60,7 +60,7 @@ pub fn acl_commands() -> CommandLineInterface {
"update",
CliCommand::new(&api2::access::acl::API_METHOD_UPDATE_ACL)
.arg_param(&["path", "role"])
- .completion_cb("userid", config::user::complete_userid)
+ .completion_cb("auth-id", config::user::complete_authid)
.completion_cb("path", config::datastore::complete_acl_path)
);
diff --git a/src/bin/proxmox_backup_manager/user.rs b/src/bin/proxmox_backup_manager/user.rs
index b1887f4e..516d27f2 100644
--- a/src/bin/proxmox_backup_manager/user.rs
+++ b/src/bin/proxmox_backup_manager/user.rs
@@ -100,7 +100,7 @@ fn list_tokens(param: Value, rpcenv: &mut dyn RpcEnvironment) -> Result<Value, E
schema: OUTPUT_FORMAT,
optional: true,
},
- auth_id: {
+ "auth-id": {
type: Authid,
},
path: {
@@ -195,8 +195,8 @@ pub fn user_commands() -> CommandLineInterface {
.insert(
"permissions",
CliCommand::new(&&API_METHOD_LIST_PERMISSIONS)
- .arg_param(&["auth_id"])
- .completion_cb("auth_id", config::user::complete_authid)
+ .arg_param(&["auth-id"])
+ .completion_cb("auth-id", config::user::complete_authid)
.completion_cb("path", config::datastore::complete_acl_path)
);
diff --git a/www/config/ACLView.js b/www/config/ACLView.js
index 67bf04f8..73edf858 100644
--- a/www/config/ACLView.js
+++ b/www/config/ACLView.js
@@ -69,7 +69,7 @@ Ext.define('PBS.config.ACLView', {
'delete': 1,
path: rec.data.path,
role: rec.data.roleid,
- auth_id: rec.data.ugid,
+ 'auth-id': rec.data.ugid,
},
callback: function() {
me.reload();
diff --git a/www/config/TokenView.js b/www/config/TokenView.js
index 88b3f194..2225d6c5 100644
--- a/www/config/TokenView.js
+++ b/www/config/TokenView.js
@@ -109,7 +109,7 @@ Ext.define('PBS.config.TokenView', {
Ext.create('Proxmox.PermissionView', {
auth_id: selection[0].data.tokenid,
- auth_id_name: 'auth_id',
+ auth_id_name: 'auth-id',
}).show();
},
diff --git a/www/config/UserView.js b/www/config/UserView.js
index eed96514..c2556b97 100644
--- a/www/config/UserView.js
+++ b/www/config/UserView.js
@@ -72,7 +72,7 @@ Ext.define('PBS.config.UserView', {
Ext.create('Proxmox.PermissionView', {
auth_id: selection[0].data.userid,
- auth_id_name: 'auth_id',
+ auth_id_name: 'auth-id',
}).show();
},
diff --git a/www/window/ACLEdit.js b/www/window/ACLEdit.js
index 42db1ff6..9ac5884f 100644
--- a/www/window/ACLEdit.js
+++ b/www/window/ACLEdit.js
@@ -33,7 +33,7 @@ Ext.define('PBS.window.ACLEdit', {
me.items.push({
xtype: 'pbsUserSelector',
fieldLabel: gettext('User'),
- name: 'auth_id',
+ name: 'auth-id',
allowBlank: false,
});
} else if (me.aclType === 'token') {
@@ -41,7 +41,7 @@ Ext.define('PBS.window.ACLEdit', {
me.items.push({
xtype: 'pbsTokenSelector',
fieldLabel: gettext('API Token'),
- name: 'auth_id',
+ name: 'auth-id',
allowBlank: false,
});
}
--
2.20.1
^ permalink raw reply [flat|nested] 4+ messages in thread
* [pbs-devel] [PATCH proxmox-backup 2/2] docs: add API tokens to documentation
2020-10-30 14:18 [pbs-devel] [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id Fabian Grünbichler
@ 2020-10-30 14:18 ` Fabian Grünbichler
2020-10-30 16:03 ` [pbs-devel] applied: " Thomas Lamprecht
2020-10-30 16:02 ` [pbs-devel] applied: [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id Thomas Lamprecht
1 sibling, 1 reply; 4+ messages in thread
From: Fabian Grünbichler @ 2020-10-30 14:18 UTC (permalink / raw)
To: pbs-devel
Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>
---
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [pbs-devel] applied: [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id
2020-10-30 14:18 [pbs-devel] [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id Fabian Grünbichler
2020-10-30 14:18 ` [pbs-devel] [PATCH proxmox-backup 2/2] docs: add API tokens to documentation Fabian Grünbichler
@ 2020-10-30 16:02 ` Thomas Lamprecht
1 sibling, 0 replies; 4+ messages in thread
From: Thomas Lamprecht @ 2020-10-30 16:02 UTC (permalink / raw)
To: Proxmox Backup Server development discussion, Fabian Grünbichler
On 30.10.20 15:18, Fabian Grünbichler wrote:
> in parameters, and fix up the completion for the ACL update parameter.
>
> Signed-off-by: Fabian Grünbichler <f.gruenbichler@proxmox.com>
> ---
> src/api2/access.rs | 2 +-
> src/api2/access/acl.rs | 2 +-
> src/bin/proxmox_backup_manager/acl.rs | 2 +-
> src/bin/proxmox_backup_manager/user.rs | 6 +++---
> www/config/ACLView.js | 2 +-
> www/config/TokenView.js | 2 +-
> www/config/UserView.js | 2 +-
> www/window/ACLEdit.js | 4 ++--
> 8 files changed, 11 insertions(+), 11 deletions(-)
>
>
applied, thanks!
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2020-10-30 16:03 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-30 14:18 [pbs-devel] [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id Fabian Grünbichler
2020-10-30 14:18 ` [pbs-devel] [PATCH proxmox-backup 2/2] docs: add API tokens to documentation Fabian Grünbichler
2020-10-30 16:03 ` [pbs-devel] applied: " Thomas Lamprecht
2020-10-30 16:02 ` [pbs-devel] applied: [PATCH proxmox-backup 1/2] api: replace auth_id with auth-id Thomas Lamprecht
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox