]>
Commit | Line | Data |
---|---|---|
04e24b14 DW |
1 | .. _user_mgmt: |
2 | ||
3 | User Management | |
4 | =============== | |
5 | ||
6 | ||
7 | User Configuration | |
8 | ------------------ | |
9 | ||
10 | .. image:: images/screenshots/pbs-gui-user-management.png | |
5565e454 | 11 | :target: _images/pbs-gui-user-management.png |
04e24b14 DW |
12 | :align: right |
13 | :alt: User management | |
14 | ||
34407477 | 15 | `Proxmox Backup`_ Server supports several authentication realms, and you need to |
04e24b14 DW |
16 | choose the realm when you add a new user. Possible realms are: |
17 | ||
18 | :pam: Linux PAM standard authentication. Use this if you want to | |
717ce406 | 19 | authenticate as a Linux system user (users need to exist on the |
04e24b14 DW |
20 | system). |
21 | ||
22 | :pbs: Proxmox Backup Server realm. This type stores hashed passwords in | |
23 | ``/etc/proxmox-backup/shadow.json``. | |
24 | ||
60589e60 DW |
25 | :openid: OpenID Connect server. Users can authenticate against an external |
26 | OpenID Connect server. | |
27 | ||
2d492a9c LW |
28 | :ldap: LDAP server. Users can authenticate against external LDAP servers. |
29 | ||
a819f056 CH |
30 | :ad: Active Directory server. Users can authenticate against external Active |
31 | Directory servers. | |
32 | ||
60589e60 DW |
33 | After installation, there is a single user, ``root@pam``, which corresponds to |
34 | the Unix superuser. User configuration information is stored in the file | |
35 | ``/etc/proxmox-backup/user.cfg``. You can use the ``proxmox-backup-manager`` | |
8c83b75a | 36 | command-line tool to list or manipulate users: |
04e24b14 DW |
37 | |
38 | .. code-block:: console | |
39 | ||
40 | # proxmox-backup-manager user list | |
41 | ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐ | |
42 | │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │ | |
43 | ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡ | |
44 | │ root@pam │ 1 │ │ │ │ │ Superuser │ | |
45 | └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘ | |
46 | ||
47 | .. image:: images/screenshots/pbs-gui-user-management-add-user.png | |
5565e454 | 48 | :target: _images/pbs-gui-user-management-add-user.png |
04e24b14 DW |
49 | :align: right |
50 | :alt: Add a new user | |
51 | ||
717ce406 DW |
52 | The superuser has full administration rights on everything, so it's recommended |
53 | to add other users with less privileges. You can add a new | |
6227b9ba DW |
54 | user with the ``user create`` subcommand or through the web |
55 | interface, under the **User Management** tab of **Configuration -> Access | |
56 | Control**. The ``create`` subcommand lets you specify many options like | |
57 | ``--email`` or ``--password``. You can update or change any user properties | |
717ce406 | 58 | using the ``user update`` subcommand later (**Edit** in the GUI): |
04e24b14 DW |
59 | |
60 | ||
61 | .. code-block:: console | |
62 | ||
63 | # proxmox-backup-manager user create john@pbs --email john@example.com | |
64 | # proxmox-backup-manager user update john@pbs --firstname John --lastname Smith | |
65 | # proxmox-backup-manager user update john@pbs --comment "An example user." | |
66 | ||
67 | .. todo:: Mention how to set password without passing plaintext password as cli argument. | |
68 | ||
69 | ||
70 | The resulting user list looks like this: | |
71 | ||
72 | .. code-block:: console | |
73 | ||
74 | # proxmox-backup-manager user list | |
75 | ┌──────────┬────────┬────────┬───────────┬──────────┬──────────────────┬──────────────────┐ | |
76 | │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │ | |
77 | ╞══════════╪════════╪════════╪═══════════╪══════════╪══════════════════╪══════════════════╡ | |
78 | │ john@pbs │ 1 │ │ John │ Smith │ john@example.com │ An example user. │ | |
79 | ├──────────┼────────┼────────┼───────────┼──────────┼──────────────────┼──────────────────┤ | |
80 | │ root@pam │ 1 │ │ │ │ │ Superuser │ | |
81 | └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘ | |
82 | ||
60589e60 | 83 | Newly created users do not have any permissions. Please read the :ref:`user_acl` |
04e24b14 DW |
84 | section to learn how to set access permissions. |
85 | ||
717ce406 | 86 | You can disable a user account by setting ``--enable`` to ``0``: |
04e24b14 DW |
87 | |
88 | .. code-block:: console | |
89 | ||
90 | # proxmox-backup-manager user update john@pbs --enable 0 | |
91 | ||
717ce406 | 92 | Or completely remove a user with: |
04e24b14 DW |
93 | |
94 | .. code-block:: console | |
95 | ||
96 | # proxmox-backup-manager user remove john@pbs | |
97 | ||
034cf70b FG |
98 | .. _user_tokens: |
99 | ||
100 | API Tokens | |
101 | ---------- | |
102 | ||
b9975249 | 103 | .. image:: images/screenshots/pbs-gui-apitoken-overview.png |
5565e454 | 104 | :target: _images/pbs-gui-apitoken-overview.png |
b9975249 DW |
105 | :align: right |
106 | :alt: API Token Overview | |
107 | ||
717ce406 | 108 | Any authenticated user can generate API tokens, which can in turn be used to |
034cf70b FG |
109 | configure various clients, instead of directly providing the username and |
110 | password. | |
111 | ||
112 | API tokens serve two purposes: | |
113 | ||
114 | #. Easy revocation in case client gets compromised | |
115 | #. Limit permissions for each client/token within the users' permission | |
116 | ||
117 | An API token consists of two parts: an identifier consisting of the user name, | |
118 | the realm and a tokenname (``user@realm!tokenname``), and a secret value. Both | |
119 | need to be provided to the client in place of the user ID (``user@realm``) and | |
4aef06f1 | 120 | the user password, respectively. |
034cf70b | 121 | |
b9975249 | 122 | .. image:: images/screenshots/pbs-gui-apitoken-secret-value.png |
5565e454 | 123 | :target: _images/pbs-gui-apitoken-secret-value.png |
b9975249 DW |
124 | :align: right |
125 | :alt: API secret value | |
126 | ||
034cf70b FG |
127 | The API token is passed from the client to the server by setting the |
128 | ``Authorization`` HTTP header with method ``PBSAPIToken`` to the value | |
129 | ``TOKENID:TOKENSECRET``. | |
130 | ||
717ce406 | 131 | You can generate tokens from the GUI or by using ``proxmox-backup-manager``: |
034cf70b FG |
132 | |
133 | .. code-block:: console | |
134 | ||
135 | # proxmox-backup-manager user generate-token john@pbs client1 | |
136 | Result: { | |
137 | "tokenid": "john@pbs!client1", | |
138 | "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde" | |
139 | } | |
140 | ||
141 | .. note:: The displayed secret value needs to be saved, since it cannot be | |
142 | displayed again after generating the API token. | |
143 | ||
144 | The ``user list-tokens`` sub-command can be used to display tokens and their | |
145 | metadata: | |
146 | ||
147 | .. code-block:: console | |
148 | ||
149 | # proxmox-backup-manager user list-tokens john@pbs | |
150 | ┌──────────────────┬────────┬────────┬─────────┐ | |
151 | │ tokenid │ enable │ expire │ comment │ | |
152 | ╞══════════════════╪════════╪════════╪═════════╡ | |
153 | │ john@pbs!client1 │ 1 │ │ │ | |
154 | └──────────────────┴────────┴────────┴─────────┘ | |
155 | ||
156 | Similarly, the ``user delete-token`` subcommand can be used to delete a token | |
157 | again. | |
158 | ||
159 | Newly generated API tokens don't have any permissions. Please read the next | |
160 | section to learn how to set access permissions. | |
161 | ||
04e24b14 DW |
162 | |
163 | .. _user_acl: | |
164 | ||
165 | Access Control | |
166 | -------------- | |
167 | ||
717ce406 | 168 | By default, new users and API tokens do not have any permissions. Instead you |
597398cb TL |
169 | need to specify what is allowed and what is not. |
170 | ||
6481fd24 | 171 | Proxmox Backup Server uses a role- and path-based permission management system. |
597398cb TL |
172 | An entry in the permissions table allows a user, group or token to take on a |
173 | specific role when accessing an 'object' or 'path'. This means that such an | |
174 | access rule can be represented as a triple of '(path, user, role)', '(path, | |
175 | group, role)' or '(path, token, role)', with the role containing a set of | |
176 | allowed actions, and the path representing the target of these actions. | |
177 | ||
178 | Privileges | |
179 | ~~~~~~~~~~ | |
180 | ||
6481fd24 | 181 | Privileges are the building blocks of access roles. They are internally |
597398cb TL |
182 | used to enforce the actual permission checks in the API. |
183 | ||
184 | We currently support the following privileges: | |
185 | ||
186 | **Sys.Audit** | |
6481fd24 | 187 | Sys.Audit allows a user to know about the system and its status. |
597398cb TL |
188 | |
189 | **Sys.Modify** | |
6481fd24 | 190 | Sys.Modify allows a user to modify system-level configuration and apply updates. |
597398cb TL |
191 | |
192 | **Sys.PowerManagement** | |
6481fd24 | 193 | Sys.Modify allows a user to power-off and reboot the system. |
597398cb TL |
194 | |
195 | **Datastore.Audit** | |
6481fd24 | 196 | Datastore.Audit allows a user to know about a datastore, including reading the |
597398cb TL |
197 | configuration entry and listing its contents. |
198 | ||
199 | **Datastore.Allocate** | |
6481fd24 | 200 | Datastore.Allocate allows a user to create or delete datastores. |
597398cb TL |
201 | |
202 | **Datastore.Modify** | |
6481fd24 | 203 | Datastore.Modify allows a user to modify a datastore and its contents, and to |
597398cb TL |
204 | create or delete namespaces inside a datastore. |
205 | ||
206 | **Datastore.Read** | |
6481fd24 | 207 | Datastore.Read allows a user to read arbitrary backup contents, independent of |
597398cb TL |
208 | the backup group owner. |
209 | ||
210 | **Datastore.Verify** | |
211 | Allows verifying the backup snapshots in a datastore. | |
212 | ||
213 | **Datastore.Backup** | |
6481fd24 | 214 | Datastore.Backup allows a user create new backup snapshots and also provides the |
597398cb TL |
215 | privileges of Datastore.Read and Datastore.Verify, but only if the backup |
216 | group is owned by the user or one of its tokens. | |
217 | ||
218 | **Datastore.Prune** | |
6481fd24 DW |
219 | Datastore.Prune allows a user to delete snapshots, but additionally requires |
220 | backup ownership. | |
597398cb TL |
221 | |
222 | **Permissions.Modify** | |
6481fd24 | 223 | Permissions.Modify allows a user to modify ACLs. |
597398cb | 224 | |
6481fd24 DW |
225 | .. note:: A user can always configure privileges for their own API tokens, as |
226 | they will be limited by the users privileges anyway. | |
597398cb TL |
227 | |
228 | **Remote.Audit** | |
6481fd24 | 229 | Remote.Audit allows a user to read the remote and the sync configuration entries. |
597398cb TL |
230 | |
231 | **Remote.Modify** | |
6481fd24 | 232 | Remote.Modify allows a user to modify the remote configuration. |
597398cb TL |
233 | |
234 | **Remote.Read** | |
6481fd24 | 235 | Remote.Read allows a user to read data from a configured `Remote`. |
597398cb TL |
236 | |
237 | **Sys.Console** | |
6481fd24 | 238 | Sys.Console allows a user to access the system's console, note that for all |
597398cb TL |
239 | but `root@pam` a valid system login is still required. |
240 | ||
241 | **Tape.Audit** | |
6481fd24 DW |
242 | Tape.Audit allows a user to read the configuration and status of tape drives, |
243 | changers and backups. | |
597398cb TL |
244 | |
245 | **Tape.Modify** | |
6481fd24 DW |
246 | Tape.Modify allows a user to modify the configuration of tape drives, changers |
247 | and backups. | |
597398cb TL |
248 | |
249 | **Tape.Write** | |
6481fd24 | 250 | Tape.Write allows a user to write to a tape media. |
597398cb TL |
251 | |
252 | **Tape.Read** | |
6481fd24 DW |
253 | Tape.Read allows a user to read tape backup configuration and contents from a |
254 | tape media. | |
597398cb TL |
255 | |
256 | **Realm.Allocate** | |
6481fd24 DW |
257 | Realm.Allocate allows a user to view, create, modify and delete authentication |
258 | realms for users. | |
597398cb TL |
259 | |
260 | Access Roles | |
261 | ~~~~~~~~~~~~ | |
262 | ||
263 | An access role combines one or more privileges into something that can be | |
6481fd24 | 264 | assigned to a user or API token on an object path. |
597398cb | 265 | |
6481fd24 | 266 | Currently, there are only built-in roles, meaning you cannot create your |
597398cb TL |
267 | own, custom role. |
268 | ||
269 | The following roles exist: | |
04e24b14 DW |
270 | |
271 | **NoAccess** | |
272 | Disable Access - nothing is allowed. | |
273 | ||
274 | **Admin** | |
597398cb | 275 | Can do anything, on the object path assigned. |
04e24b14 DW |
276 | |
277 | **Audit** | |
597398cb TL |
278 | Can view the status and configuration of things, but is not allowed to change |
279 | settings. | |
04e24b14 DW |
280 | |
281 | **DatastoreAdmin** | |
597398cb | 282 | Can do anything on *existing* datastores. |
04e24b14 DW |
283 | |
284 | **DatastoreAudit** | |
597398cb TL |
285 | Can view datastore metrics, settings and list content. But is not allowed to |
286 | read the actual data. | |
04e24b14 DW |
287 | |
288 | **DatastoreReader** | |
6481fd24 | 289 | Can inspect a datastore's or namespace's content and do restores. |
04e24b14 DW |
290 | |
291 | **DatastoreBackup** | |
292 | Can backup and restore owned backups. | |
293 | ||
294 | **DatastorePowerUser** | |
597398cb | 295 | Can backup, restore, and prune *owned* backups. |
04e24b14 DW |
296 | |
297 | **RemoteAdmin** | |
298 | Can do anything on remotes. | |
299 | ||
300 | **RemoteAudit** | |
301 | Can view remote settings. | |
302 | ||
303 | **RemoteSyncOperator** | |
304 | Is allowed to read data from a remote. | |
305 | ||
597398cb | 306 | **TapeAdmin** |
6481fd24 | 307 | Can do anything related to tape backup. |
60589e60 | 308 | |
597398cb | 309 | **TapeAudit** |
6481fd24 | 310 | Can view tape-related metrics, configuration and status. |
597398cb | 311 | |
60589e60 | 312 | **TapeOperator** |
6481fd24 | 313 | Can do tape backup and restore, but cannot change any configuration. |
60589e60 DW |
314 | |
315 | **TapeReader** | |
6481fd24 | 316 | Can read and inspect tape configuration and media content. |
60589e60 | 317 | |
1d9ba1cc TL |
318 | Objects and Paths |
319 | ~~~~~~~~~~~~~~~~~ | |
320 | ||
6481fd24 | 321 | Access permissions are assigned to objects, such as a datastore, namespace or |
1d9ba1cc TL |
322 | some system resources. |
323 | ||
6481fd24 | 324 | We use filesystem-like paths to address these objects. These paths form a |
1d9ba1cc TL |
325 | natural tree, and permissions of higher levels (shorter paths) can optionally |
326 | be propagated down within this hierarchy. | |
327 | ||
6481fd24 DW |
328 | Paths can be templated, meaning they can refer to the actual id of a |
329 | configuration entry. When an API call requires permissions on a templated | |
1d9ba1cc | 330 | path, the path may contain references to parameters of the API call. These |
6481fd24 | 331 | references are specified in curly brackets. |
1d9ba1cc TL |
332 | |
333 | Some examples are: | |
334 | ||
f8c78d84 AZ |
335 | .. table:: |
336 | :align: left | |
337 | ||
338 | =========================== ========================================================= | |
339 | ``/datastore`` Access to *all* datastores on a Proxmox Backup server | |
340 | ``/datastore/{store}`` Access to a specific datastore on a Proxmox Backup server | |
341 | ``/datastore/{store}/{ns}`` Access to a specific namespace on a specific datastore | |
342 | ``/remote`` Access to all remote entries | |
343 | ``/system/network`` Access to configure the host network | |
344 | ``/tape/`` Access to tape devices, pools and jobs | |
345 | ``/access/users`` User administration | |
346 | ``/access/openid/{id}`` Administrative access to a specific OpenID Connect realm | |
347 | =========================== ========================================================= | |
1d9ba1cc TL |
348 | |
349 | Inheritance | |
350 | ^^^^^^^^^^^ | |
351 | ||
352 | As mentioned earlier, object paths form a file system like tree, and | |
353 | permissions can be inherited by objects down that tree through the propagate | |
354 | flag, which is set by default. We use the following inheritance rules: | |
355 | ||
6481fd24 | 356 | * Permissions for API tokens are always limited to those of the user. |
1d9ba1cc TL |
357 | * Permissions on deeper, more specific levels replace those inherited from an |
358 | upper level. | |
359 | ||
360 | ||
361 | Configuration & Management | |
362 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
363 | ||
364 | .. image:: images/screenshots/pbs-gui-permissions-add.png | |
5565e454 | 365 | :target: _images/pbs-gui-permissions-add.png |
04e24b14 DW |
366 | :align: right |
367 | :alt: Add permissions for user | |
368 | ||
369 | Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The | |
370 | file contains 5 fields, separated using a colon (':') as a delimiter. A typical | |
371 | entry takes the form: | |
372 | ||
373 | ``acl:1:/datastore:john@pbs:DatastoreBackup`` | |
374 | ||
375 | The data represented in each field is as follows: | |
376 | ||
377 | #. ``acl`` identifier | |
378 | #. A ``1`` or ``0``, representing whether propagation is enabled or disabled, | |
379 | respectively | |
380 | #. The object on which the permission is set. This can be a specific object | |
381 | (single datastore, remote, etc.) or a top level object, which with | |
382 | propagation enabled, represents all children of the object also. | |
034cf70b | 383 | #. The user(s)/token(s) for which the permission is set |
04e24b14 DW |
384 | #. The role being set |
385 | ||
034cf70b FG |
386 | You can manage permissions via **Configuration -> Access Control -> |
387 | Permissions** in the web interface. Likewise, you can use the ``acl`` | |
388 | subcommand to manage and monitor user permissions from the command line. For | |
389 | example, the command below will add the user ``john@pbs`` as a | |
390 | **DatastoreAdmin** for the datastore ``store1``, located at | |
391 | ``/backup/disk1/store1``: | |
04e24b14 DW |
392 | |
393 | .. code-block:: console | |
394 | ||
034cf70b | 395 | # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs |
04e24b14 | 396 | |
034cf70b | 397 | You can list the ACLs of each user/token using the following command: |
04e24b14 DW |
398 | |
399 | .. code-block:: console | |
400 | ||
401 | # proxmox-backup-manager acl list | |
477ebe6b FE |
402 | ┌──────────┬───────────────────┬───────────┬────────────────┐ |
403 | │ ugid │ path │ propagate │ roleid │ | |
404 | ╞══════════╪═══════════════════╪═══════════╪════════════════╡ | |
405 | │ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │ | |
406 | └──────────┴───────────────────┴───────────┴────────────────┘ | |
04e24b14 | 407 | |
717ce406 DW |
408 | A single user/token can be assigned multiple permission sets for different |
409 | datastores. | |
04e24b14 DW |
410 | |
411 | .. Note:: | |
412 | Naming convention is important here. For datastores on the host, | |
413 | you must use the convention ``/datastore/{storename}``. For example, to set | |
414 | permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use | |
415 | ``/datastore/store2`` for the path. For remote stores, use the convention | |
416 | ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the | |
417 | remote (see `Remote` below) and ``{storename}`` is the name of the datastore on | |
418 | the remote. | |
419 | ||
717ce406 | 420 | API Token Permissions |
034cf70b FG |
421 | ~~~~~~~~~~~~~~~~~~~~~ |
422 | ||
717ce406 DW |
423 | API token permissions are calculated based on ACLs containing their ID, |
424 | independently of those of their corresponding user. The resulting permission set | |
034cf70b FG |
425 | on a given path is then intersected with that of the corresponding user. |
426 | ||
427 | In practice this means: | |
428 | ||
429 | #. API tokens require their own ACL entries | |
430 | #. API tokens can never do more than their corresponding user | |
431 | ||
717ce406 | 432 | Effective Permissions |
034cf70b FG |
433 | ~~~~~~~~~~~~~~~~~~~~~ |
434 | ||
717ce406 | 435 | To calculate and display the effective permission set of a user or API token, |
034cf70b FG |
436 | you can use the ``proxmox-backup-manager user permission`` command: |
437 | ||
438 | .. code-block:: console | |
04e24b14 | 439 | |
477ebe6b | 440 | # proxmox-backup-manager user permissions john@pbs --path /datastore/store1 |
034cf70b | 441 | Privileges with (*) have the propagate flag set |
717ce406 | 442 | |
034cf70b FG |
443 | Path: /datastore/store1 |
444 | - Datastore.Audit (*) | |
445 | - Datastore.Backup (*) | |
446 | - Datastore.Modify (*) | |
447 | - Datastore.Prune (*) | |
448 | - Datastore.Read (*) | |
477ebe6b | 449 | - Datastore.Verify (*) |
717ce406 | 450 | |
034cf70b | 451 | # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1' |
477ebe6b | 452 | # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1 |
034cf70b | 453 | Privileges with (*) have the propagate flag set |
717ce406 | 454 | |
034cf70b FG |
455 | Path: /datastore/store1 |
456 | - Datastore.Backup (*) | |
f9fcac51 TL |
457 | |
458 | .. _user_tfa: | |
28eaff20 | 459 | |
717ce406 | 460 | Two-Factor Authentication |
f9fcac51 TL |
461 | ------------------------- |
462 | ||
463 | Introduction | |
464 | ~~~~~~~~~~~~ | |
465 | ||
207f763d DW |
466 | With simple authentication, only a password (single factor) is required to |
467 | successfully claim an identity (authenticate), for example, to be able to log in | |
468 | as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if | |
717ce406 | 469 | the password gets leaked or stolen, anybody can use it to log in - even if they |
207f763d DW |
470 | should not be allowed to do so. |
471 | ||
472 | With two-factor authentication (TFA), a user is asked for an additional factor | |
473 | to verify their authenticity. Rather than relying on something only the user | |
474 | knows (a password), this extra factor requires something only the user has, for | |
475 | example, a piece of hardware (security key) or a secret saved on the user's | |
476 | smartphone. This prevents a remote user from gaining unauthorized access to an | |
477 | account, as even if they have the password, they will not have access to the | |
478 | physical object (second factor). | |
f9fcac51 | 479 | |
2f617a45 | 480 | .. image:: images/screenshots/pbs-gui-tfa-login.png |
5565e454 | 481 | :target: _images/pbs-gui-tfa-login.png |
2f617a45 TL |
482 | :align: right |
483 | :alt: Add a new user | |
484 | ||
f9fcac51 TL |
485 | Available Second Factors |
486 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
487 | ||
207f763d DW |
488 | You can set up multiple second factors, in order to avoid a situation in which |
489 | losing your smartphone or security key locks you out of your account | |
490 | permanently. | |
f9fcac51 | 491 | |
207f763d DW |
492 | Proxmox Backup Server supports three different two-factor authentication |
493 | methods: | |
f9fcac51 TL |
494 | |
495 | * TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_). | |
207f763d | 496 | A short code derived from a shared secret and the current time, it changes |
f9fcac51 TL |
497 | every 30 seconds. |
498 | ||
499 | * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_). | |
500 | A general standard for authentication. It is implemented by various security | |
207f763d | 501 | devices, like hardware keys or trusted platform modules (TPM) from a computer |
f9fcac51 TL |
502 | or smart phone. |
503 | ||
504 | * Single use Recovery Keys. A list of keys which should either be printed out | |
207f763d DW |
505 | and locked in a secure place or saved digitally in an electronic vault. |
506 | Each key can be used only once. These are perfect for ensuring that you are | |
507 | not locked out, even if all of your other second factors are lost or corrupt. | |
f9fcac51 TL |
508 | |
509 | ||
510 | Setup | |
511 | ~~~~~ | |
512 | ||
513 | .. _user_tfa_setup_totp: | |
28eaff20 | 514 | |
f9fcac51 TL |
515 | TOTP |
516 | ^^^^ | |
2f617a45 TL |
517 | |
518 | .. image:: images/screenshots/pbs-gui-tfa-add-totp.png | |
5565e454 | 519 | :target: _images/pbs-gui-tfa-add-totp.png |
2f617a45 TL |
520 | :align: right |
521 | :alt: Add a new user | |
522 | ||
207f763d | 523 | There is no server setup required. Simply install a TOTP app on your |
f9fcac51 TL |
524 | smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the |
525 | Proxmox Backup Server web-interface to add a TOTP factor. | |
526 | ||
527 | .. _user_tfa_setup_webauthn: | |
28eaff20 | 528 | |
f9fcac51 TL |
529 | WebAuthn |
530 | ^^^^^^^^ | |
531 | ||
207f763d | 532 | For WebAuthn to work, you need to have two things: |
f9fcac51 | 533 | |
717ce406 | 534 | * A trusted HTTPS certificate (for example, by using `Let's Encrypt |
5bf9b0b0 DC |
535 | <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_). |
536 | While it probably works with an untrusted certificate, some browsers may warn | |
537 | or refuse WebAuthn operations if it is not trusted. | |
f9fcac51 | 538 | |
018d29f7 | 539 | * Setup the WebAuthn configuration (see **Configuration -> Other** in |
717ce406 DW |
540 | the Proxmox Backup Server web interface). This can be auto-filled in most |
541 | setups. | |
f9fcac51 | 542 | |
207f763d | 543 | Once you have fulfilled both of these requirements, you can add a WebAuthn |
60589e60 DW |
544 | configuration in the **Two Factor Authentication** tab of the **Access Control** |
545 | panel. | |
f9fcac51 TL |
546 | |
547 | .. _user_tfa_setup_recovery_keys: | |
28eaff20 | 548 | |
f9fcac51 TL |
549 | Recovery Keys |
550 | ^^^^^^^^^^^^^ | |
551 | ||
2f617a45 | 552 | .. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png |
5565e454 | 553 | :target: _images/pbs-gui-tfa-add-recovery-keys.png |
2f617a45 TL |
554 | :align: right |
555 | :alt: Add a new user | |
556 | ||
207f763d | 557 | Recovery key codes do not need any preparation; you can simply create a set of |
60589e60 DW |
558 | recovery keys in the **Two Factor Authentication** tab of the **Access Control** |
559 | panel. | |
f9fcac51 TL |
560 | |
561 | .. note:: There can only be one set of single-use recovery keys per user at any | |
562 | time. | |
563 | ||
564 | TFA and Automated Access | |
565 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
566 | ||
207f763d | 567 | Two-factor authentication is only implemented for the web-interface. You should |
f9fcac51 | 568 | use :ref:`API Tokens <user_tokens>` for all other use cases, especially |
207f763d | 569 | non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE |
f9fcac51 | 570 | as a storage). |
2d492a9c | 571 | |
c724c006 TL |
572 | .. _user_tfa_lockout: |
573 | ||
574 | Limits and Lockout of Two-Factor Authentication | |
575 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
576 | ||
577 | A second factor is meant to protect users if their password is somehow leaked | |
578 | or guessed. However, some factors could still be broken by brute force. For | |
579 | this reason, users will be locked out after too many failed 2nd factor login | |
580 | attempts. | |
581 | ||
582 | For TOTP, 8 failed attempts will disable the user's TOTP factors. They are | |
583 | unlocked when logging in with a recovery key. If TOTP was the only available | |
584 | factor, admin intervention is required, and it is highly recommended to require | |
585 | the user to change their password immediately. | |
586 | ||
587 | Since FIDO2/Webauthn and recovery keys are less susceptible to brute force | |
588 | attacks, the limit there is higher (100 tries), but all second factors are | |
589 | blocked for an hour when exceeded. | |
590 | ||
591 | An admin can unlock a user's Two-Factor Authentication at any time via the user | |
592 | list view in the web UI, or using the command line: | |
593 | ||
594 | .. code-block:: console | |
595 | ||
935b69a5 | 596 | proxmox-backup-manager user tfa unlock joe@pbs |
c724c006 | 597 | |
2d492a9c LW |
598 | |
599 | Authentication Realms | |
600 | --------------------- | |
601 | ||
602 | .. _user_realms_ldap: | |
603 | ||
604 | LDAP | |
605 | ~~~~ | |
606 | ||
3f44c29c LW |
607 | Proxmox Backup Server can utilize external LDAP servers for user authentication. |
608 | To achieve this, a realm of the type ``ldap`` has to be configured. | |
2d492a9c | 609 | |
3f44c29c LW |
610 | In LDAP, users are uniquely identified by their domain (``dn``). For instance, |
611 | in the following LDIF dataset, the user ``user1`` has the unique domain | |
612 | ``uid=user1,ou=People,dc=ldap-test,dc=com``: | |
2d492a9c LW |
613 | |
614 | ||
615 | .. code-block:: console | |
616 | ||
617 | # user1 of People at ldap-test.com | |
618 | dn: uid=user1,ou=People,dc=ldap-test,dc=com | |
619 | objectClass: top | |
620 | objectClass: person | |
621 | objectClass: organizationalPerson | |
622 | objectClass: inetOrgPerson | |
623 | uid: user1 | |
624 | cn: Test User 1 | |
625 | sn: Testers | |
626 | description: This is the first test user. | |
627 | ||
3f44c29c LW |
628 | In in similar manner, Proxmox Backup Server uses user identifiers (``userid``) |
629 | to uniquely identify users. Thus, it is necessary to establish a mapping | |
db10278b FG |
630 | between a Proxmox Backup Server ``userid`` and an LDAP ``dn``. This mapping is |
631 | established by the ``user-attr`` configuration parameter - it contains the name | |
632 | of the LDAP attribute containing a valid Proxmox Backup Server user identifier. | |
2d492a9c | 633 | |
3f44c29c LW |
634 | For the example above, setting ``user-attr`` to ``uid`` will have the effect |
635 | that the user ``user1@<realm-name>`` will be mapped to the LDAP entity | |
db10278b FG |
636 | ``uid=user1,ou=People,dc=ldap-test,dc=com``. On user login, Proxmox Backup |
637 | Server will perform a `subtree search` under the configured Base Domain | |
638 | (``base-dn``) to query the user's ``dn``. Once the ``dn`` is known, an LDAP | |
639 | bind operation is performed to authenticate the user against the LDAP server. | |
2d492a9c | 640 | |
3f44c29c LW |
641 | As not all LDAP servers allow `anonymous` search operations, it is possible to |
642 | configure a bind domain (``bind-dn``) and a bind password (``password``). | |
db10278b FG |
643 | If set, Proxmox Backup Server will bind to the LDAP server using these |
644 | credentials before performing any search operations. | |
2d492a9c LW |
645 | |
646 | A full list of all configuration parameters can be found at :ref:`domains.cfg`. | |
647 | ||
3f44c29c LW |
648 | .. note:: In order to allow a particular user to authenticate using the LDAP |
649 | server, you must also add them as a user of that realm in Proxmox Backup | |
650 | Server. This can be carried out automatically with syncing. | |
2d492a9c | 651 | |
a819f056 CH |
652 | .. _user_realms_ad: |
653 | ||
654 | Active Directory | |
655 | ~~~~~~~~~~~~~~~~ | |
656 | ||
657 | Proxmox Backup Server can also utilize external Microsoft Active Directory | |
658 | servers for user authentication. | |
659 | To achieve this, a realm of the type ``ad`` has to be configured. | |
660 | ||
661 | For an Active Directory realm, the authentication domain name and the server | |
662 | address must be specified. Most options from :ref:`user_realms_ldap` apply to | |
663 | Active Directory as well, most importantly the bind credentials ``bind-dn`` | |
664 | and ``password``. This is typically required by default for Microsoft Active | |
665 | Directory. The ``bind-dn`` can be specified either in AD-specific | |
666 | ``user@company.net`` syntax or the commen LDAP-DN syntax. | |
667 | ||
668 | The authentication domain name must only be specified if anonymous bind is | |
669 | requested. If bind credentials are given, the domain name is automatically | |
670 | inferred from the bind users' base domain, as reported by the Active Directory | |
671 | server. | |
672 | ||
673 | A full list of all configuration parameters can be found at :ref:`domains.cfg`. | |
674 | ||
675 | .. note:: In order to allow a particular user to authenticate using the Active | |
676 | Directory server, you must also add them as a user of that realm in Proxmox | |
677 | Backup Server. This can be carried out automatically with syncing. | |
678 | ||
679 | .. note:: Currently, case-insensitive usernames are not supported. | |
680 | ||
681 | User Synchronization in LDAP/AD realms | |
682 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
683 | ||
684 | It is possible to automatically sync users for LDAP and AD-based realms, rather | |
685 | than having to add them to Proxmox Backup Server manually. Synchronization | |
686 | options can be set in the LDAP realm configuration dialog window in the GUI and | |
687 | via the ``proxmox-backup-manager ldap`` and ``proxmox-backup-manager ad`` | |
688 | commands, respectively. | |
689 | ||
690 | User synchronization can be started in the GUI under **Configuration > Access | |
691 | Control > Realms** by selecting a realm and pressing the `Sync` button. In the | |
692 | sync dialog, some of the default options set in the realm configuration can be | |
693 | overridden. Alternatively, user synchronization can also be started via the | |
694 | ``proxmox-backup-manager ldap sync`` and ``proxmox-backup-manager ad sync`` | |
695 | command, respectively. |