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 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 After installation, there is a single user ``root@pam``, which
25 corresponds to the Unix superuser. User configuration information is stored in the file
26 ``/etc/proxmox-backup/user.cfg``. You can use the
27 ``proxmox-backup-manager`` command line tool to list or manipulate
30 .. code-block:: console
32 # proxmox-backup-manager user list
33 ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐
34 │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │
35 ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡
36 │ root@pam │ 1 │ │ │ │ │ Superuser │
37 └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘
39 .. image:: images/screenshots/pbs-gui-user-management-add-user.png
43 The superuser has full administration rights on everything, so you
44 normally want to add other users with less privileges. You can add a new
45 user with the ``user create`` subcommand or through the web
46 interface, under the **User Management** tab of **Configuration -> Access
47 Control**. The ``create`` subcommand lets you specify many options like
48 ``--email`` or ``--password``. You can update or change any user properties
49 using the ``update`` subcommand later (**Edit** in the GUI):
52 .. code-block:: console
54 # proxmox-backup-manager user create john@pbs --email john@example.com
55 # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith
56 # proxmox-backup-manager user update john@pbs --comment "An example user."
58 .. todo:: Mention how to set password without passing plaintext password as cli argument.
61 The resulting user list looks like this:
63 .. code-block:: console
65 # proxmox-backup-manager user list
66 ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐
67 │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │
68 ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡
69 │ john@pbs │ 1 │ │ John │ Smith │ john@example.com │ An example user. │
70 ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤
71 │ root@pam │ 1 │ │ │ │ │ Superuser │
72 └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘
74 Newly created users do not have any permissions. Please read the Access Control
75 section to learn how to set access permissions.
77 If you want to disable a user account, you can do that by setting ``--enable`` to ``0``
79 .. code-block:: console
81 # proxmox-backup-manager user update john@pbs --enable 0
83 Or completely remove the user with:
85 .. code-block:: console
87 # proxmox-backup-manager user remove john@pbs
94 .. image:: images/screenshots/pbs-gui-apitoken-overview.png
96 :alt: API Token Overview
98 Any authenticated user can generate API tokens which can in turn be used to
99 configure various clients, instead of directly providing the username and
102 API tokens serve two purposes:
104 #. Easy revocation in case client gets compromised
105 #. Limit permissions for each client/token within the users' permission
107 An API token consists of two parts: an identifier consisting of the user name,
108 the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both
109 need to be provided to the client in place of the user ID (``user@realm``) and
110 the user password, respectively.
112 .. image:: images/screenshots/pbs-gui-apitoken-secret-value.png
114 :alt: API secret value
116 The API token is passed from the client to the server by setting the
117 ``Authorization`` HTTP header with method ``PBSAPIToken`` to the value
118 ``TOKENID:TOKENSECRET``.
120 Generating new tokens can done using ``proxmox-backup-manager`` or the GUI:
122 .. code-block:: console
124 # proxmox-backup-manager user generate-token john@pbs client1
126 "tokenid": "john@pbs!client1",
127 "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde"
130 .. note:: The displayed secret value needs to be saved, since it cannot be
131 displayed again after generating the API token.
133 The ``user list-tokens`` sub-command can be used to display tokens and their
136 .. code-block:: console
138 # proxmox-backup-manager user list-tokens john@pbs
139 ┌──────────────────┬────────┬────────┬─────────┐
140 │ tokenid │ enable │ expire │ comment │
141 ╞══════════════════╪════════╪════════╪═════════╡
142 │ john@pbs!client1 │ 1 │ │ │
143 └──────────────────┴────────┴────────┴─────────┘
145 Similarly, the ``user delete-token`` subcommand can be used to delete a token
148 Newly generated API tokens don't have any permissions. Please read the next
149 section to learn how to set access permissions.
157 By default new users and API tokens do not have any permission. Instead you
158 need to specify what is allowed and what is not. You can do this by assigning
159 roles to users/tokens on specific objects like datastores or remotes. The
160 following roles exist:
163 Disable Access - nothing is allowed.
169 Can view things, but is not allowed to change settings.
172 Can do anything on datastores.
175 Can view datastore settings and list content. But
176 is not allowed to read the actual data.
179 Can Inspect datastore content and can do restores.
182 Can backup and restore owned backups.
184 **DatastorePowerUser**
185 Can backup, restore, and prune owned backups.
188 Can do anything on remotes.
191 Can view remote settings.
193 **RemoteSyncOperator**
194 Is allowed to read data from a remote.
196 .. image:: images/screenshots/pbs-gui-user-management-add-user.png
198 :alt: Add permissions for user
200 Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
201 file contains 5 fields, separated using a colon (':') as a delimiter. A typical
202 entry takes the form:
204 ``acl:1:/datastore:john@pbs:DatastoreBackup``
206 The data represented in each field is as follows:
208 #. ``acl`` identifier
209 #. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
211 #. The object on which the permission is set. This can be a specific object
212 (single datastore, remote, etc.) or a top level object, which with
213 propagation enabled, represents all children of the object also.
214 #. The user(s)/token(s) for which the permission is set
215 #. The role being set
217 You can manage permissions via **Configuration -> Access Control ->
218 Permissions** in the web interface. Likewise, you can use the ``acl``
219 subcommand to manage and monitor user permissions from the command line. For
220 example, the command below will add the user ``john@pbs`` as a
221 **DatastoreAdmin** for the datastore ``store1``, located at
222 ``/backup/disk1/store1``:
224 .. code-block:: console
226 # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs
228 You can list the ACLs of each user/token using the following command:
230 .. code-block:: console
232 # proxmox-backup-manager acl list
233 ┌──────────┬───────────────────┬───────────┬────────────────┐
234 │ ugid │ path │ propagate │ roleid │
235 ╞══════════╪═══════════════════╪═══════════╪════════════════╡
236 │ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │
237 └──────────┴───────────────────┴───────────┴────────────────┘
239 A single user/token can be assigned multiple permission sets for different datastores.
242 Naming convention is important here. For datastores on the host,
243 you must use the convention ``/datastore/{storename}``. For example, to set
244 permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
245 ``/datastore/store2`` for the path. For remote stores, use the convention
246 ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
247 remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
250 API Token permissions
251 ~~~~~~~~~~~~~~~~~~~~~
253 API token permissions are calculated based on ACLs containing their ID
254 independent of those of their corresponding user. The resulting permission set
255 on a given path is then intersected with that of the corresponding user.
257 In practice this means:
259 #. API tokens require their own ACL entries
260 #. API tokens can never do more than their corresponding user
262 Effective permissions
263 ~~~~~~~~~~~~~~~~~~~~~
265 To calculate and display the effective permission set of a user or API token
266 you can use the ``proxmox-backup-manager user permission`` command:
268 .. code-block:: console
270 # proxmox-backup-manager user permissions john@pbs --path /datastore/store1
271 Privileges with (*) have the propagate flag set
273 Path: /datastore/store1
274 - Datastore.Audit (*)
275 - Datastore.Backup (*)
276 - Datastore.Modify (*)
277 - Datastore.Prune (*)
279 - Datastore.Verify (*)
281 # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
282 # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1
283 Privileges with (*) have the propagate flag set
285 Path: /datastore/store1
286 - Datastore.Backup (*)
290 Two-factor authentication
291 -------------------------
296 Simple authentication requires only secret piece of evidence (one factor) that
297 a user can successfully claim a identiy (authenticate), for example, that you
298 are allowed to login as `root@pam` on a specific Proxmox Backup Server.
299 If the password gets stolen, or leaked in another way, anybody can use it to
300 login - even if they should not be allowed to do so.
302 With Two-factor authentication (TFA) a user is asked for an additional factor,
303 to proof his authenticity. The extra factor is different from a password
304 (something only the user knows), it is something only the user has, for example
305 a piece of hardware (security key) or an secret saved on the users smartphone.
307 This means that a remote user can never get hold on such a physical object. So,
308 even if that user would know your password they cannot successfully
309 authenticate as you, as your second factor is missing.
311 .. image:: images/screenshots/pbs-gui-tfa-login.png
315 Available Second Factors
316 ~~~~~~~~~~~~~~~~~~~~~~~~
318 You can setup more than one second factor to avoid that losing your smartphone
319 or security key permanently locks you out from your account.
321 There are three different two-factor authentication methods supported:
323 * TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_).
324 A short code derived from a shared secret and the current time, it switches
327 * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
328 A general standard for authentication. It is implemented by various security
329 devices like hardware keys or trusted platform modules (TPM) from a computer
332 * Single use Recovery Keys. A list of keys which should either be printed out
333 and locked in a secure fault or saved digitally in a electronic vault.
334 Each key can be used only once, they are perfect for ensuring you are not
335 locked out even if all of your other second factors are lost or corrupt.
341 .. _user_tfa_setup_totp:
346 .. image:: images/screenshots/pbs-gui-tfa-add-totp.png
350 There is not server setup required, simply install a TOTP app on your
351 smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
352 Proxmox Backup Server web-interface to add a TOTP factor.
354 .. _user_tfa_setup_webauthn:
359 For WebAuthn to work you need to have two things:
361 * a trusted HTTPS certificate (for example, by using `Let's Encrypt
362 <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_)
364 * setup the WebAuthn configuration (see *Configuration -> Authentication* in the
365 Proxmox Backup Server web-interface). This can be auto-filled in most setups.
367 Once you fullfilled both of those requirements, you can add a WebAuthn
368 configuration in the *Access Control* panel.
370 .. _user_tfa_setup_recovery_keys:
375 .. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png
379 Recovery key codes do not need any preparation, you can simply create a set of
380 recovery keys in the *Access Control* panel.
382 .. note:: There can only be one set of single-use recovery keys per user at any
385 TFA and Automated Access
386 ~~~~~~~~~~~~~~~~~~~~~~~~
388 Two-factor authentication is only implemented for the web-interface, you should
389 use :ref:`API Tokens <user_tokens>` for all other use cases, especially
390 non-interactive ones (for example, adding a Proxmox Backup server to Proxmox VE