10 .. image:: images/screenshots/pbs-gui-user-management.png
11 :target: _images/pbs-gui-user-management.png
15 Proxmox Backup Server supports several authentication realms, and you need to
16 choose the realm when you add a new user. Possible realms are:
18 :pam: Linux PAM standard authentication. Use this if you want to
19 authenticate as a Linux system user (users need to exist on the
22 :pbs: Proxmox Backup Server realm. This type stores hashed passwords in
23 ``/etc/proxmox-backup/shadow.json``.
25 :openid: OpenID Connect server. Users can authenticate against an external
26 OpenID Connect server.
28 :ldap: LDAP server. Users can authenticate against external LDAP servers.
30 After installation, there is a single user, ``root@pam``, which corresponds to
31 the Unix superuser. User configuration information is stored in the file
32 ``/etc/proxmox-backup/user.cfg``. You can use the ``proxmox-backup-manager``
33 command line tool to list or manipulate users:
35 .. code-block:: console
37 # proxmox-backup-manager user list
38 ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐
39 │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │
40 ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡
41 │ root@pam │ 1 │ │ │ │ │ Superuser │
42 └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘
44 .. image:: images/screenshots/pbs-gui-user-management-add-user.png
45 :target: _images/pbs-gui-user-management-add-user.png
49 The superuser has full administration rights on everything, so it's recommended
50 to add other users with less privileges. You can add a new
51 user with the ``user create`` subcommand or through the web
52 interface, under the **User Management** tab of **Configuration -> Access
53 Control**. The ``create`` subcommand lets you specify many options like
54 ``--email`` or ``--password``. You can update or change any user properties
55 using the ``user update`` subcommand later (**Edit** in the GUI):
58 .. code-block:: console
60 # proxmox-backup-manager user create john@pbs --email john@example.com
61 # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith
62 # proxmox-backup-manager user update john@pbs --comment "An example user."
64 .. todo:: Mention how to set password without passing plaintext password as cli argument.
67 The resulting user list looks like this:
69 .. code-block:: console
71 # proxmox-backup-manager user list
72 ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐
73 │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │
74 ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡
75 │ john@pbs │ 1 │ │ John │ Smith │ john@example.com │ An example user. │
76 ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤
77 │ root@pam │ 1 │ │ │ │ │ Superuser │
78 └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘
80 Newly created users do not have any permissions. Please read the :ref:`user_acl`
81 section to learn how to set access permissions.
83 You can disable a user account by setting ``--enable`` to ``0``:
85 .. code-block:: console
87 # proxmox-backup-manager user update john@pbs --enable 0
89 Or completely remove a user with:
91 .. code-block:: console
93 # proxmox-backup-manager user remove john@pbs
100 .. image:: images/screenshots/pbs-gui-apitoken-overview.png
101 :target: _images/pbs-gui-apitoken-overview.png
103 :alt: API Token Overview
105 Any authenticated user can generate API tokens, which can in turn be used to
106 configure various clients, instead of directly providing the username and
109 API tokens serve two purposes:
111 #. Easy revocation in case client gets compromised
112 #. Limit permissions for each client/token within the users' permission
114 An API token consists of two parts: an identifier consisting of the user name,
115 the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both
116 need to be provided to the client in place of the user ID (``user@realm``) and
117 the user password, respectively.
119 .. image:: images/screenshots/pbs-gui-apitoken-secret-value.png
120 :target: _images/pbs-gui-apitoken-secret-value.png
122 :alt: API secret value
124 The API token is passed from the client to the server by setting the
125 ``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
126 ``TOKENID:TOKENSECRET``.
128 You can generate tokens from the GUI or by using ``proxmox-backup-manager``:
130 .. code-block:: console
132 # proxmox-backup-manager user generate-token john@pbs client1
134 "tokenid": "john@pbs!client1",
135 "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde"
138 .. note:: The displayed secret value needs to be saved, since it cannot be
139 displayed again after generating the API token.
141 The ``user list-tokens`` sub-command can be used to display tokens and their
144 .. code-block:: console
146 # proxmox-backup-manager user list-tokens john@pbs
147 ┌──────────────────┬────────┬────────┬─────────┐
148 │ tokenid │ enable │ expire │ comment │
149 ╞══════════════════╪════════╪════════╪═════════╡
150 │ john@pbs!client1 │ 1 │ │ │
151 └──────────────────┴────────┴────────┴─────────┘
153 Similarly, the ``user delete-token`` subcommand can be used to delete a token
156 Newly generated API tokens don't have any permissions. Please read the next
157 section to learn how to set access permissions.
165 By default, new users and API tokens do not have any permissions. Instead you
166 need to specify what is allowed and what is not.
168 Proxmox Backup Server uses a role- and path-based permission management system.
169 An entry in the permissions table allows a user, group or token to take on a
170 specific role when accessing an 'object' or 'path'. This means that such an
171 access rule can be represented as a triple of '(path, user, role)', '(path,
172 group, role)' or '(path, token, role)', with the role containing a set of
173 allowed actions, and the path representing the target of these actions.
178 Privileges are the building blocks of access roles. They are internally
179 used to enforce the actual permission checks in the API.
181 We currently support the following privileges:
184 Sys.Audit allows a user to know about the system and its status.
187 Sys.Modify allows a user to modify system-level configuration and apply updates.
189 **Sys.PowerManagement**
190 Sys.Modify allows a user to power-off and reboot the system.
193 Datastore.Audit allows a user to know about a datastore, including reading the
194 configuration entry and listing its contents.
196 **Datastore.Allocate**
197 Datastore.Allocate allows a user to create or delete datastores.
200 Datastore.Modify allows a user to modify a datastore and its contents, and to
201 create or delete namespaces inside a datastore.
204 Datastore.Read allows a user to read arbitrary backup contents, independent of
205 the backup group owner.
208 Allows verifying the backup snapshots in a datastore.
211 Datastore.Backup allows a user create new backup snapshots and also provides the
212 privileges of Datastore.Read and Datastore.Verify, but only if the backup
213 group is owned by the user or one of its tokens.
216 Datastore.Prune allows a user to delete snapshots, but additionally requires
219 **Permissions.Modify**
220 Permissions.Modify allows a user to modify ACLs.
222 .. note:: A user can always configure privileges for their own API tokens, as
223 they will be limited by the users privileges anyway.
226 Remote.Audit allows a user to read the remote and the sync configuration entries.
229 Remote.Modify allows a user to modify the remote configuration.
232 Remote.Read allows a user to read data from a configured `Remote`.
235 Sys.Console allows a user to access the system's console, note that for all
236 but `root@pam` a valid system login is still required.
239 Tape.Audit allows a user to read the configuration and status of tape drives,
240 changers and backups.
243 Tape.Modify allows a user to modify the configuration of tape drives, changers
247 Tape.Write allows a user to write to a tape media.
250 Tape.Read allows a user to read tape backup configuration and contents from a
254 Realm.Allocate allows a user to view, create, modify and delete authentication
260 An access role combines one or more privileges into something that can be
261 assigned to a user or API token on an object path.
263 Currently, there are only built-in roles, meaning you cannot create your
266 The following roles exist:
269 Disable Access - nothing is allowed.
272 Can do anything, on the object path assigned.
275 Can view the status and configuration of things, but is not allowed to change
279 Can do anything on *existing* datastores.
282 Can view datastore metrics, settings and list content. But is not allowed to
283 read the actual data.
286 Can inspect a datastore's or namespace's content and do restores.
289 Can backup and restore owned backups.
291 **DatastorePowerUser**
292 Can backup, restore, and prune *owned* backups.
295 Can do anything on remotes.
298 Can view remote settings.
300 **RemoteSyncOperator**
301 Is allowed to read data from a remote.
304 Can do anything related to tape backup.
307 Can view tape-related metrics, configuration and status.
310 Can do tape backup and restore, but cannot change any configuration.
313 Can read and inspect tape configuration and media content.
318 Access permissions are assigned to objects, such as a datastore, namespace or
319 some system resources.
321 We use filesystem-like paths to address these objects. These paths form a
322 natural tree, and permissions of higher levels (shorter paths) can optionally
323 be propagated down within this hierarchy.
325 Paths can be templated, meaning they can refer to the actual id of a
326 configuration entry. When an API call requires permissions on a templated
327 path, the path may contain references to parameters of the API call. These
328 references are specified in curly brackets.
332 * `/datastore`: Access to *all* datastores on a Proxmox Backup server
333 * `/datastore/{store}`: Access to a specific datastore on a Proxmox Backup
335 * `/datastore/{store}/{ns}`: Access to a specific namespace on a specific
337 * `/remote`: Access to all remote entries
338 * `/system/network`: Access to configure the host network
339 * `/tape/`: Access to tape devices, pools and jobs
340 * `/access/users`: User administration
341 * `/access/openid/{id}`: Administrative access to a specific OpenID Connect realm
346 As mentioned earlier, object paths form a file system like tree, and
347 permissions can be inherited by objects down that tree through the propagate
348 flag, which is set by default. We use the following inheritance rules:
350 * Permissions for API tokens are always limited to those of the user.
351 * Permissions on deeper, more specific levels replace those inherited from an
355 Configuration & Management
356 ~~~~~~~~~~~~~~~~~~~~~~~~~~
358 .. image:: images/screenshots/pbs-gui-permissions-add.png
359 :target: _images/pbs-gui-permissions-add.png
361 :alt: Add permissions for user
363 Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
364 file contains 5 fields, separated using a colon (':') as a delimiter. A typical
365 entry takes the form:
367 ``acl:1:/datastore:john@pbs:DatastoreBackup``
369 The data represented in each field is as follows:
371 #. ``acl`` identifier
372 #. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
374 #. The object on which the permission is set. This can be a specific object
375 (single datastore, remote, etc.) or a top level object, which with
376 propagation enabled, represents all children of the object also.
377 #. The user(s)/token(s) for which the permission is set
378 #. The role being set
380 You can manage permissions via **Configuration -> Access Control ->
381 Permissions** in the web interface. Likewise, you can use the ``acl``
382 subcommand to manage and monitor user permissions from the command line. For
383 example, the command below will add the user ``john@pbs`` as a
384 **DatastoreAdmin** for the datastore ``store1``, located at
385 ``/backup/disk1/store1``:
387 .. code-block:: console
389 # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs
391 You can list the ACLs of each user/token using the following command:
393 .. code-block:: console
395 # proxmox-backup-manager acl list
396 ┌──────────┬───────────────────┬───────────┬────────────────┐
397 │ ugid │ path │ propagate │ roleid │
398 ╞══════════╪═══════════════════╪═══════════╪════════════════╡
399 │ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │
400 └──────────┴───────────────────┴───────────┴────────────────┘
402 A single user/token can be assigned multiple permission sets for different
406 Naming convention is important here. For datastores on the host,
407 you must use the convention ``/datastore/{storename}``. For example, to set
408 permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
409 ``/datastore/store2`` for the path. For remote stores, use the convention
410 ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
411 remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
414 API Token Permissions
415 ~~~~~~~~~~~~~~~~~~~~~
417 API token permissions are calculated based on ACLs containing their ID,
418 independently of those of their corresponding user. The resulting permission set
419 on a given path is then intersected with that of the corresponding user.
421 In practice this means:
423 #. API tokens require their own ACL entries
424 #. API tokens can never do more than their corresponding user
426 Effective Permissions
427 ~~~~~~~~~~~~~~~~~~~~~
429 To calculate and display the effective permission set of a user or API token,
430 you can use the ``proxmox-backup-manager user permission`` command:
432 .. code-block:: console
434 # proxmox-backup-manager user permissions john@pbs --path /datastore/store1
435 Privileges with (*) have the propagate flag set
437 Path: /datastore/store1
438 - Datastore.Audit (*)
439 - Datastore.Backup (*)
440 - Datastore.Modify (*)
441 - Datastore.Prune (*)
443 - Datastore.Verify (*)
445 # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
446 # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1
447 Privileges with (*) have the propagate flag set
449 Path: /datastore/store1
450 - Datastore.Backup (*)
454 Two-Factor Authentication
455 -------------------------
460 With simple authentication, only a password (single factor) is required to
461 successfully claim an identity (authenticate), for example, to be able to log in
462 as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if
463 the password gets leaked or stolen, anybody can use it to log in - even if they
464 should not be allowed to do so.
466 With two-factor authentication (TFA), a user is asked for an additional factor
467 to verify their authenticity. Rather than relying on something only the user
468 knows (a password), this extra factor requires something only the user has, for
469 example, a piece of hardware (security key) or a secret saved on the user's
470 smartphone. This prevents a remote user from gaining unauthorized access to an
471 account, as even if they have the password, they will not have access to the
472 physical object (second factor).
474 .. image:: images/screenshots/pbs-gui-tfa-login.png
475 :target: _images/pbs-gui-tfa-login.png
479 Available Second Factors
480 ~~~~~~~~~~~~~~~~~~~~~~~~
482 You can set up multiple second factors, in order to avoid a situation in which
483 losing your smartphone or security key locks you out of your account
486 Proxmox Backup Server supports three different two-factor authentication
489 * TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_).
490 A short code derived from a shared secret and the current time, it changes
493 * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
494 A general standard for authentication. It is implemented by various security
495 devices, like hardware keys or trusted platform modules (TPM) from a computer
498 * Single use Recovery Keys. A list of keys which should either be printed out
499 and locked in a secure place or saved digitally in an electronic vault.
500 Each key can be used only once. These are perfect for ensuring that you are
501 not locked out, even if all of your other second factors are lost or corrupt.
507 .. _user_tfa_setup_totp:
512 .. image:: images/screenshots/pbs-gui-tfa-add-totp.png
513 :target: _images/pbs-gui-tfa-add-totp.png
517 There is no server setup required. Simply install a TOTP app on your
518 smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
519 Proxmox Backup Server web-interface to add a TOTP factor.
521 .. _user_tfa_setup_webauthn:
526 For WebAuthn to work, you need to have two things:
528 * A trusted HTTPS certificate (for example, by using `Let's Encrypt
529 <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_).
530 While it probably works with an untrusted certificate, some browsers may warn
531 or refuse WebAuthn operations if it is not trusted.
533 * Setup the WebAuthn configuration (see **Configuration -> Authentication** in
534 the Proxmox Backup Server web interface). This can be auto-filled in most
537 Once you have fulfilled both of these requirements, you can add a WebAuthn
538 configuration in the **Two Factor Authentication** tab of the **Access Control**
541 .. _user_tfa_setup_recovery_keys:
546 .. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png
547 :target: _images/pbs-gui-tfa-add-recovery-keys.png
551 Recovery key codes do not need any preparation; you can simply create a set of
552 recovery keys in the **Two Factor Authentication** tab of the **Access Control**
555 .. note:: There can only be one set of single-use recovery keys per user at any
558 TFA and Automated Access
559 ~~~~~~~~~~~~~~~~~~~~~~~~
561 Two-factor authentication is only implemented for the web-interface. You should
562 use :ref:`API Tokens <user_tokens>` for all other use cases, especially
563 non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE
567 Authentication Realms
568 ---------------------
570 .. _user_realms_ldap:
575 Proxmox Backup Server can utilize external LDAP servers for user authentication.
576 To achieve this, a realm of the type ``ldap`` has to be configured.
578 In LDAP, users are uniquely identified by their domain (``dn``). For instance,
579 in the following LDIF dataset, the user ``user1`` has the unique domain
580 ``uid=user1,ou=People,dc=ldap-test,dc=com``:
583 .. code-block:: console
585 # user1 of People at ldap-test.com
586 dn: uid=user1,ou=People,dc=ldap-test,dc=com
589 objectClass: organizationalPerson
590 objectClass: inetOrgPerson
594 description: This is the first test user.
596 In in similar manner, Proxmox Backup Server uses user identifiers (``userid``)
597 to uniquely identify users. Thus, it is necessary to establish a mapping
598 between PBS's ``userid`` and LDAP's ``dn``. This mapping is established by
599 the ``user-attr`` configuration parameter - it contains the name of the LDAP
600 attribute containing a valid PBS user identifier.
602 For the example above, setting ``user-attr`` to ``uid`` will have the effect
603 that the user ``user1@<realm-name>`` will be mapped to the LDAP entity
604 ``uid=user1,ou=People,dc=ldap-test,dc=com``. On user login, PBS will perform
605 a `subtree search` under the configured Base Domain (``base-dn``) to query
606 the user's ``dn``. Once the ``dn`` is known, an LDAP bind operation is performed
607 to authenticate the user against the LDAP server.
609 As not all LDAP servers allow `anonymous` search operations, it is possible to
610 configure a bind domain (``bind-dn``) and a bind password (``password``).
611 If set, PBS will bind to the LDAP server using these credentials before
612 performing any search operations.
614 A full list of all configuration parameters can be found at :ref:`domains.cfg`.
616 .. note:: In order to allow a particular user to authenticate using the LDAP
617 server, you must also add them as a user of that realm in Proxmox Backup
618 Server. This can be carried out automatically with syncing.
620 User Synchronization in LDAP realms
621 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
623 It is possible to automatically sync users for LDAP-based realms, rather than
624 having to add them to Proxmox VE manually. Synchronization options can be set
625 in the LDAP realm configuration dialog window in the GUI and via the
626 ``proxmox-backup-manager ldap create/update`` command.
627 User synchronization can started in the GUI at
628 Configuration > Access Control > Realms by selecting a realm and pressing the
629 `Sync` button. In the sync dialog, some of the default options set in the realm
630 configuration can be overridden. Alternatively, user synchronization can also
631 be started via the ``proxmox-backup-manager ldap sync`` command.