10 .. image:: images/screenshots/pbs-gui-user-management.png
14 Proxmox Backup Server supports several authentication realms, and you need to
15 choose the realm when you add a new user. Possible realms are:
17 :pam: Linux PAM standard authentication. Use this if you want to
18 authenticate as a Linux system user (users need to exist on the
21 :pbs: Proxmox Backup Server realm. This type stores hashed passwords in
22 ``/etc/proxmox-backup/shadow.json``.
24 :openid: OpenID Connect server. Users can authenticate against an external
25 OpenID Connect server.
27 After installation, there is a single user, ``root@pam``, which corresponds to
28 the Unix superuser. User configuration information is stored in the file
29 ``/etc/proxmox-backup/user.cfg``. You can use the ``proxmox-backup-manager``
30 command line tool to list or manipulate users:
32 .. code-block:: console
34 # proxmox-backup-manager user list
35 ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐
36 │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │
37 ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡
38 │ root@pam │ 1 │ │ │ │ │ Superuser │
39 └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘
41 .. image:: images/screenshots/pbs-gui-user-management-add-user.png
45 The superuser has full administration rights on everything, so it's recommended
46 to add other users with less privileges. You can add a new
47 user with the ``user create`` subcommand or through the web
48 interface, under the **User Management** tab of **Configuration -> Access
49 Control**. The ``create`` subcommand lets you specify many options like
50 ``--email`` or ``--password``. You can update or change any user properties
51 using the ``user update`` subcommand later (**Edit** in the GUI):
54 .. code-block:: console
56 # proxmox-backup-manager user create john@pbs --email john@example.com
57 # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith
58 # proxmox-backup-manager user update john@pbs --comment "An example user."
60 .. todo:: Mention how to set password without passing plaintext password as cli argument.
63 The resulting user list looks like this:
65 .. code-block:: console
67 # proxmox-backup-manager user list
68 ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐
69 │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │
70 ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡
71 │ john@pbs │ 1 │ │ John │ Smith │ john@example.com │ An example user. │
72 ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤
73 │ root@pam │ 1 │ │ │ │ │ Superuser │
74 └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘
76 Newly created users do not have any permissions. Please read the :ref:`user_acl`
77 section to learn how to set access permissions.
79 You can disable a user account by setting ``--enable`` to ``0``:
81 .. code-block:: console
83 # proxmox-backup-manager user update john@pbs --enable 0
85 Or completely remove a user with:
87 .. code-block:: console
89 # proxmox-backup-manager user remove john@pbs
96 .. image:: images/screenshots/pbs-gui-apitoken-overview.png
98 :alt: API Token Overview
100 Any authenticated user can generate API tokens, which can in turn be used to
101 configure various clients, instead of directly providing the username and
104 API tokens serve two purposes:
106 #. Easy revocation in case client gets compromised
107 #. Limit permissions for each client/token within the users' permission
109 An API token consists of two parts: an identifier consisting of the user name,
110 the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both
111 need to be provided to the client in place of the user ID (``user@realm``) and
112 the user password, respectively.
114 .. image:: images/screenshots/pbs-gui-apitoken-secret-value.png
116 :alt: API secret value
118 The API token is passed from the client to the server by setting the
119 ``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
120 ``TOKENID:TOKENSECRET``.
122 You can generate tokens from the GUI or by using ``proxmox-backup-manager``:
124 .. code-block:: console
126 # proxmox-backup-manager user generate-token john@pbs client1
128 "tokenid": "john@pbs!client1",
129 "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde"
132 .. note:: The displayed secret value needs to be saved, since it cannot be
133 displayed again after generating the API token.
135 The ``user list-tokens`` sub-command can be used to display tokens and their
138 .. code-block:: console
140 # proxmox-backup-manager user list-tokens john@pbs
141 ┌──────────────────┬────────┬────────┬─────────┐
142 │ tokenid │ enable │ expire │ comment │
143 ╞══════════════════╪════════╪════════╪═════════╡
144 │ john@pbs!client1 │ 1 │ │ │
145 └──────────────────┴────────┴────────┴─────────┘
147 Similarly, the ``user delete-token`` subcommand can be used to delete a token
150 Newly generated API tokens don't have any permissions. Please read the next
151 section to learn how to set access permissions.
159 By default, new users and API tokens do not have any permissions. Instead you
160 need to specify what is allowed and what is not.
162 Proxmox Backup Server uses a role and path based permission management system.
163 An entry in the permissions table allows a user, group or token to take on a
164 specific role when accessing an 'object' or 'path'. This means that such an
165 access rule can be represented as a triple of '(path, user, role)', '(path,
166 group, role)' or '(path, token, role)', with the role containing a set of
167 allowed actions, and the path representing the target of these actions.
172 Privileges are the atoms that access roles are made off. They are internally
173 used to enforce the actual permission checks in the API.
175 We currently support the following privileges:
178 Sys.Audit allows one to know about the system and its status.
181 Sys.Modify allows one to modify system-level configuration and apply updates.
183 **Sys.PowerManagement**
184 Sys.Modify allows one to to poweroff or reboot the system.
187 Datastore.Audit allows one to know about a datastore, including reading the
188 configuration entry and listing its contents.
190 **Datastore.Allocate**
191 Datastore.Allocate allows one to create or deleting datastores.
194 Datastore.Modify allows one to modify a datastore and its contents, and to
195 create or delete namespaces inside a datastore.
198 Datastore.Read allows one to read arbitrary backup contents, independent of
199 the backup group owner.
202 Allows verifying the backup snapshots in a datastore.
205 Datastore.Backup allows one create new backup snapshot and gives one also the
206 privileges of Datastore.Read and Datastore.Verify, but only if the backup
207 group is owned by the user or one of its tokens.
210 Datastore.Prune allows one to delete snapshots, but additionally requires
213 **Permissions.Modify**
214 Permissions.Modify allows one to modifying ACLs
216 .. note:: One can always configure privileges for their own API tokens, as
217 they will clamped by the users privileges anyway.
220 Remote.Audit allows one to read the remote and the sync configuration entries
223 Remote.Modify allows one to modify the remote configuration
226 Remote.Read allows one to read data from a configured `Remote`
229 Sys.Console allows one to access to the system's console, note that for all
230 but `root@pam` a valid system login is still required.
233 Tape.Audit allows one to read the configuration and status of tape drives,
237 Tape.Modify allows one to modify the configuration of tape drives, changers
241 Tape.Write allows one to write to a tape media
244 Tape.Read allows one to read tape backup configuration and contents from a
248 Realm.Allocate allows one to view, create, modify and delete authentication
254 An access role combines one or more privileges into something that can be
255 assigned to an user or API token on an object path.
257 Currently there are only built-in roles, that means, you cannot create your
260 The following roles exist:
263 Disable Access - nothing is allowed.
266 Can do anything, on the object path assigned.
269 Can view the status and configuration of things, but is not allowed to change
273 Can do anything on *existing* datastores.
276 Can view datastore metrics, settings and list content. But is not allowed to
277 read the actual data.
280 Can inspect a datastore's or namespaces content and do restores.
283 Can backup and restore owned backups.
285 **DatastorePowerUser**
286 Can backup, restore, and prune *owned* backups.
289 Can do anything on remotes.
292 Can view remote settings.
294 **RemoteSyncOperator**
295 Is allowed to read data from a remote.
298 Can do anything related to tape backup
301 Can view tape related metrics, configuration and status
304 Can do tape backup and restore, but cannot change any configuration
307 Can read and inspect tape configuration and media content
312 Access permissions are assigned to objects, such as a datastore, a namespace or
313 some system resources.
315 We use file system like paths to address these objects. These paths form a
316 natural tree, and permissions of higher levels (shorter paths) can optionally
317 be propagated down within this hierarchy.
319 Paths can be templated, that means they can refer to the actual id of an
320 configuration entry. When an API call requires permissions on a templated
321 path, the path may contain references to parameters of the API call. These
322 references are specified in curly braces.
326 * `/datastore`: Access to *all* datastores on a Proxmox Backup server
327 * `/datastore/{store}`: Access to a specific datastore on a Proxmox Backup
329 * `/datastore/{store}/{ns}`: Access to a specific namespace on a specific
331 * `/remote`: Access to all remote entries
332 * `/system/network`: Access to configuring the host network
333 * `/tape/`: Access to tape devices, pools and jobs
334 * `/access/users`: User administration
335 * `/access/openid/{id}`: Administrative access to a specific OpenID Connect realm
340 As mentioned earlier, object paths form a file system like tree, and
341 permissions can be inherited by objects down that tree through the propagate
342 flag, which is set by default. We use the following inheritance rules:
344 * Permissions for API tokens are always clamped to the one of the user.
345 * Permissions on deeper, more specific levels replace those inherited from an
349 Configuration & Management
350 ~~~~~~~~~~~~~~~~~~~~~~~~~~
352 .. image:: images/screenshots/pbs-gui-permissions-add.png
354 :alt: Add permissions for user
356 Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
357 file contains 5 fields, separated using a colon (':') as a delimiter. A typical
358 entry takes the form:
360 ``acl:1:/datastore:john@pbs:DatastoreBackup``
362 The data represented in each field is as follows:
364 #. ``acl`` identifier
365 #. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
367 #. The object on which the permission is set. This can be a specific object
368 (single datastore, remote, etc.) or a top level object, which with
369 propagation enabled, represents all children of the object also.
370 #. The user(s)/token(s) for which the permission is set
371 #. The role being set
373 You can manage permissions via **Configuration -> Access Control ->
374 Permissions** in the web interface. Likewise, you can use the ``acl``
375 subcommand to manage and monitor user permissions from the command line. For
376 example, the command below will add the user ``john@pbs`` as a
377 **DatastoreAdmin** for the datastore ``store1``, located at
378 ``/backup/disk1/store1``:
380 .. code-block:: console
382 # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs
384 You can list the ACLs of each user/token using the following command:
386 .. code-block:: console
388 # proxmox-backup-manager acl list
389 ┌──────────┬───────────────────┬───────────┬────────────────┐
390 │ ugid │ path │ propagate │ roleid │
391 ╞══════════╪═══════════════════╪═══════════╪════════════════╡
392 │ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │
393 └──────────┴───────────────────┴───────────┴────────────────┘
395 A single user/token can be assigned multiple permission sets for different
399 Naming convention is important here. For datastores on the host,
400 you must use the convention ``/datastore/{storename}``. For example, to set
401 permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
402 ``/datastore/store2`` for the path. For remote stores, use the convention
403 ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
404 remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
407 API Token Permissions
408 ~~~~~~~~~~~~~~~~~~~~~
410 API token permissions are calculated based on ACLs containing their ID,
411 independently of those of their corresponding user. The resulting permission set
412 on a given path is then intersected with that of the corresponding user.
414 In practice this means:
416 #. API tokens require their own ACL entries
417 #. API tokens can never do more than their corresponding user
419 Effective Permissions
420 ~~~~~~~~~~~~~~~~~~~~~
422 To calculate and display the effective permission set of a user or API token,
423 you can use the ``proxmox-backup-manager user permission`` command:
425 .. code-block:: console
427 # proxmox-backup-manager user permissions john@pbs --path /datastore/store1
428 Privileges with (*) have the propagate flag set
430 Path: /datastore/store1
431 - Datastore.Audit (*)
432 - Datastore.Backup (*)
433 - Datastore.Modify (*)
434 - Datastore.Prune (*)
436 - Datastore.Verify (*)
438 # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
439 # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1
440 Privileges with (*) have the propagate flag set
442 Path: /datastore/store1
443 - Datastore.Backup (*)
447 Two-Factor Authentication
448 -------------------------
453 With simple authentication, only a password (single factor) is required to
454 successfully claim an identity (authenticate), for example, to be able to log in
455 as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if
456 the password gets leaked or stolen, anybody can use it to log in - even if they
457 should not be allowed to do so.
459 With two-factor authentication (TFA), a user is asked for an additional factor
460 to verify their authenticity. Rather than relying on something only the user
461 knows (a password), this extra factor requires something only the user has, for
462 example, a piece of hardware (security key) or a secret saved on the user's
463 smartphone. This prevents a remote user from gaining unauthorized access to an
464 account, as even if they have the password, they will not have access to the
465 physical object (second factor).
467 .. image:: images/screenshots/pbs-gui-tfa-login.png
471 Available Second Factors
472 ~~~~~~~~~~~~~~~~~~~~~~~~
474 You can set up multiple second factors, in order to avoid a situation in which
475 losing your smartphone or security key locks you out of your account
478 Proxmox Backup Server supports three different two-factor authentication
481 * TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_).
482 A short code derived from a shared secret and the current time, it changes
485 * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
486 A general standard for authentication. It is implemented by various security
487 devices, like hardware keys or trusted platform modules (TPM) from a computer
490 * Single use Recovery Keys. A list of keys which should either be printed out
491 and locked in a secure place or saved digitally in an electronic vault.
492 Each key can be used only once. These are perfect for ensuring that you are
493 not locked out, even if all of your other second factors are lost or corrupt.
499 .. _user_tfa_setup_totp:
504 .. image:: images/screenshots/pbs-gui-tfa-add-totp.png
508 There is no server setup required. Simply install a TOTP app on your
509 smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
510 Proxmox Backup Server web-interface to add a TOTP factor.
512 .. _user_tfa_setup_webauthn:
517 For WebAuthn to work, you need to have two things:
519 * A trusted HTTPS certificate (for example, by using `Let's Encrypt
520 <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_).
521 While it probably works with an untrusted certificate, some browsers may warn
522 or refuse WebAuthn operations if it is not trusted.
524 * Setup the WebAuthn configuration (see **Configuration -> Authentication** in
525 the Proxmox Backup Server web interface). This can be auto-filled in most
528 Once you have fulfilled both of these requirements, you can add a WebAuthn
529 configuration in the **Two Factor Authentication** tab of the **Access Control**
532 .. _user_tfa_setup_recovery_keys:
537 .. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png
541 Recovery key codes do not need any preparation; you can simply create a set of
542 recovery keys in the **Two Factor Authentication** tab of the **Access Control**
545 .. note:: There can only be one set of single-use recovery keys per user at any
548 TFA and Automated Access
549 ~~~~~~~~~~~~~~~~~~~~~~~~
551 Two-factor authentication is only implemented for the web-interface. You should
552 use :ref:`API Tokens <user_tokens>` for all other use cases, especially
553 non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE