]>
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 | |
11 | :align: right | |
12 | :alt: User management | |
13 | ||
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: | |
16 | ||
17 | :pam: Linux PAM standard authentication. Use this if you want to | |
717ce406 | 18 | authenticate as a Linux system user (users need to exist on the |
04e24b14 DW |
19 | system). |
20 | ||
21 | :pbs: Proxmox Backup Server realm. This type stores hashed passwords in | |
22 | ``/etc/proxmox-backup/shadow.json``. | |
23 | ||
60589e60 DW |
24 | :openid: OpenID Connect server. Users can authenticate against an external |
25 | OpenID Connect server. | |
26 | ||
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: | |
04e24b14 DW |
31 | |
32 | .. code-block:: console | |
33 | ||
34 | # proxmox-backup-manager user list | |
35 | ┌─────────────┬────────┬────────┬───────────┬──────────┬────────────────┬────────────────────┐ | |
36 | │ userid │ enable │ expire │ firstname │ lastname │ email │ comment │ | |
37 | ╞═════════════╪════════╪════════╪═══════════╪══════════╪════════════════╪════════════════════╡ | |
38 | │ root@pam │ 1 │ │ │ │ │ Superuser │ | |
39 | └─────────────┴────────┴────────┴───────────┴──────────┴────────────────┴────────────────────┘ | |
40 | ||
41 | .. image:: images/screenshots/pbs-gui-user-management-add-user.png | |
42 | :align: right | |
43 | :alt: Add a new user | |
44 | ||
717ce406 DW |
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 | |
6227b9ba DW |
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 | |
717ce406 | 51 | using the ``user update`` subcommand later (**Edit** in the GUI): |
04e24b14 DW |
52 | |
53 | ||
54 | .. code-block:: console | |
55 | ||
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." | |
59 | ||
60 | .. todo:: Mention how to set password without passing plaintext password as cli argument. | |
61 | ||
62 | ||
63 | The resulting user list looks like this: | |
64 | ||
65 | .. code-block:: console | |
66 | ||
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 | └──────────┴────────┴────────┴───────────┴──────────┴──────────────────┴──────────────────┘ | |
75 | ||
60589e60 | 76 | Newly created users do not have any permissions. Please read the :ref:`user_acl` |
04e24b14 DW |
77 | section to learn how to set access permissions. |
78 | ||
717ce406 | 79 | You can disable a user account by setting ``--enable`` to ``0``: |
04e24b14 DW |
80 | |
81 | .. code-block:: console | |
82 | ||
83 | # proxmox-backup-manager user update john@pbs --enable 0 | |
84 | ||
717ce406 | 85 | Or completely remove a user with: |
04e24b14 DW |
86 | |
87 | .. code-block:: console | |
88 | ||
89 | # proxmox-backup-manager user remove john@pbs | |
90 | ||
034cf70b FG |
91 | .. _user_tokens: |
92 | ||
93 | API Tokens | |
94 | ---------- | |
95 | ||
b9975249 DW |
96 | .. image:: images/screenshots/pbs-gui-apitoken-overview.png |
97 | :align: right | |
98 | :alt: API Token Overview | |
99 | ||
717ce406 | 100 | Any authenticated user can generate API tokens, which can in turn be used to |
034cf70b FG |
101 | configure various clients, instead of directly providing the username and |
102 | password. | |
103 | ||
104 | API tokens serve two purposes: | |
105 | ||
106 | #. Easy revocation in case client gets compromised | |
107 | #. Limit permissions for each client/token within the users' permission | |
108 | ||
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 | |
4aef06f1 | 112 | the user password, respectively. |
034cf70b | 113 | |
b9975249 DW |
114 | .. image:: images/screenshots/pbs-gui-apitoken-secret-value.png |
115 | :align: right | |
116 | :alt: API secret value | |
117 | ||
034cf70b FG |
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``. | |
121 | ||
717ce406 | 122 | You can generate tokens from the GUI or by using ``proxmox-backup-manager``: |
034cf70b FG |
123 | |
124 | .. code-block:: console | |
125 | ||
126 | # proxmox-backup-manager user generate-token john@pbs client1 | |
127 | Result: { | |
128 | "tokenid": "john@pbs!client1", | |
129 | "value": "d63e505a-e3ec-449a-9bc7-1da610d4ccde" | |
130 | } | |
131 | ||
132 | .. note:: The displayed secret value needs to be saved, since it cannot be | |
133 | displayed again after generating the API token. | |
134 | ||
135 | The ``user list-tokens`` sub-command can be used to display tokens and their | |
136 | metadata: | |
137 | ||
138 | .. code-block:: console | |
139 | ||
140 | # proxmox-backup-manager user list-tokens john@pbs | |
141 | ┌──────────────────┬────────┬────────┬─────────┐ | |
142 | │ tokenid │ enable │ expire │ comment │ | |
143 | ╞══════════════════╪════════╪════════╪═════════╡ | |
144 | │ john@pbs!client1 │ 1 │ │ │ | |
145 | └──────────────────┴────────┴────────┴─────────┘ | |
146 | ||
147 | Similarly, the ``user delete-token`` subcommand can be used to delete a token | |
148 | again. | |
149 | ||
150 | Newly generated API tokens don't have any permissions. Please read the next | |
151 | section to learn how to set access permissions. | |
152 | ||
04e24b14 DW |
153 | |
154 | .. _user_acl: | |
155 | ||
156 | Access Control | |
157 | -------------- | |
158 | ||
717ce406 | 159 | By default, new users and API tokens do not have any permissions. Instead you |
034cf70b | 160 | need to specify what is allowed and what is not. You can do this by assigning |
717ce406 | 161 | roles to users/tokens on specific objects, like datastores or remotes. The |
04e24b14 DW |
162 | following roles exist: |
163 | ||
164 | **NoAccess** | |
165 | Disable Access - nothing is allowed. | |
166 | ||
167 | **Admin** | |
168 | Can do anything. | |
169 | ||
170 | **Audit** | |
171 | Can view things, but is not allowed to change settings. | |
172 | ||
173 | **DatastoreAdmin** | |
174 | Can do anything on datastores. | |
175 | ||
176 | **DatastoreAudit** | |
177 | Can view datastore settings and list content. But | |
178 | is not allowed to read the actual data. | |
179 | ||
180 | **DatastoreReader** | |
717ce406 | 181 | Can Inspect datastore content and do restores. |
04e24b14 DW |
182 | |
183 | **DatastoreBackup** | |
184 | Can backup and restore owned backups. | |
185 | ||
186 | **DatastorePowerUser** | |
187 | Can backup, restore, and prune owned backups. | |
188 | ||
189 | **RemoteAdmin** | |
190 | Can do anything on remotes. | |
191 | ||
192 | **RemoteAudit** | |
193 | Can view remote settings. | |
194 | ||
195 | **RemoteSyncOperator** | |
196 | Is allowed to read data from a remote. | |
197 | ||
60589e60 DW |
198 | **TapeAudit** |
199 | Can view tape related configuration and status | |
200 | ||
201 | **TapeAdministrat** | |
202 | Can do anything related to tape backup | |
203 | ||
204 | **TapeOperator** | |
205 | Can do tape backup and restore (but no configuration changes) | |
206 | ||
207 | **TapeReader** | |
208 | Can read and inspect tape configuration and media content | |
209 | ||
b9975249 | 210 | .. image:: images/screenshots/pbs-gui-user-management-add-user.png |
04e24b14 DW |
211 | :align: right |
212 | :alt: Add permissions for user | |
213 | ||
214 | Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The | |
215 | file contains 5 fields, separated using a colon (':') as a delimiter. A typical | |
216 | entry takes the form: | |
217 | ||
218 | ``acl:1:/datastore:john@pbs:DatastoreBackup`` | |
219 | ||
220 | The data represented in each field is as follows: | |
221 | ||
222 | #. ``acl`` identifier | |
223 | #. A ``1`` or ``0``, representing whether propagation is enabled or disabled, | |
224 | respectively | |
225 | #. The object on which the permission is set. This can be a specific object | |
226 | (single datastore, remote, etc.) or a top level object, which with | |
227 | propagation enabled, represents all children of the object also. | |
034cf70b | 228 | #. The user(s)/token(s) for which the permission is set |
04e24b14 DW |
229 | #. The role being set |
230 | ||
034cf70b FG |
231 | You can manage permissions via **Configuration -> Access Control -> |
232 | Permissions** in the web interface. Likewise, you can use the ``acl`` | |
233 | subcommand to manage and monitor user permissions from the command line. For | |
234 | example, the command below will add the user ``john@pbs`` as a | |
235 | **DatastoreAdmin** for the datastore ``store1``, located at | |
236 | ``/backup/disk1/store1``: | |
04e24b14 DW |
237 | |
238 | .. code-block:: console | |
239 | ||
034cf70b | 240 | # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs |
04e24b14 | 241 | |
034cf70b | 242 | You can list the ACLs of each user/token using the following command: |
04e24b14 DW |
243 | |
244 | .. code-block:: console | |
245 | ||
246 | # proxmox-backup-manager acl list | |
477ebe6b FE |
247 | ┌──────────┬───────────────────┬───────────┬────────────────┐ |
248 | │ ugid │ path │ propagate │ roleid │ | |
249 | ╞══════════╪═══════════════════╪═══════════╪════════════════╡ | |
250 | │ john@pbs │ /datastore/store1 │ 1 │ DatastoreAdmin │ | |
251 | └──────────┴───────────────────┴───────────┴────────────────┘ | |
04e24b14 | 252 | |
717ce406 DW |
253 | A single user/token can be assigned multiple permission sets for different |
254 | datastores. | |
04e24b14 DW |
255 | |
256 | .. Note:: | |
257 | Naming convention is important here. For datastores on the host, | |
258 | you must use the convention ``/datastore/{storename}``. For example, to set | |
259 | permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use | |
260 | ``/datastore/store2`` for the path. For remote stores, use the convention | |
261 | ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the | |
262 | remote (see `Remote` below) and ``{storename}`` is the name of the datastore on | |
263 | the remote. | |
264 | ||
717ce406 | 265 | API Token Permissions |
034cf70b FG |
266 | ~~~~~~~~~~~~~~~~~~~~~ |
267 | ||
717ce406 DW |
268 | API token permissions are calculated based on ACLs containing their ID, |
269 | independently of those of their corresponding user. The resulting permission set | |
034cf70b FG |
270 | on a given path is then intersected with that of the corresponding user. |
271 | ||
272 | In practice this means: | |
273 | ||
274 | #. API tokens require their own ACL entries | |
275 | #. API tokens can never do more than their corresponding user | |
276 | ||
717ce406 | 277 | Effective Permissions |
034cf70b FG |
278 | ~~~~~~~~~~~~~~~~~~~~~ |
279 | ||
717ce406 | 280 | To calculate and display the effective permission set of a user or API token, |
034cf70b FG |
281 | you can use the ``proxmox-backup-manager user permission`` command: |
282 | ||
283 | .. code-block:: console | |
04e24b14 | 284 | |
477ebe6b | 285 | # proxmox-backup-manager user permissions john@pbs --path /datastore/store1 |
034cf70b | 286 | Privileges with (*) have the propagate flag set |
717ce406 | 287 | |
034cf70b FG |
288 | Path: /datastore/store1 |
289 | - Datastore.Audit (*) | |
290 | - Datastore.Backup (*) | |
291 | - Datastore.Modify (*) | |
292 | - Datastore.Prune (*) | |
293 | - Datastore.Read (*) | |
477ebe6b | 294 | - Datastore.Verify (*) |
717ce406 | 295 | |
034cf70b | 296 | # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1' |
477ebe6b | 297 | # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1 |
034cf70b | 298 | Privileges with (*) have the propagate flag set |
717ce406 | 299 | |
034cf70b FG |
300 | Path: /datastore/store1 |
301 | - Datastore.Backup (*) | |
f9fcac51 TL |
302 | |
303 | .. _user_tfa: | |
28eaff20 | 304 | |
717ce406 | 305 | Two-Factor Authentication |
f9fcac51 TL |
306 | ------------------------- |
307 | ||
308 | Introduction | |
309 | ~~~~~~~~~~~~ | |
310 | ||
207f763d DW |
311 | With simple authentication, only a password (single factor) is required to |
312 | successfully claim an identity (authenticate), for example, to be able to log in | |
313 | as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if | |
717ce406 | 314 | the password gets leaked or stolen, anybody can use it to log in - even if they |
207f763d DW |
315 | should not be allowed to do so. |
316 | ||
317 | With two-factor authentication (TFA), a user is asked for an additional factor | |
318 | to verify their authenticity. Rather than relying on something only the user | |
319 | knows (a password), this extra factor requires something only the user has, for | |
320 | example, a piece of hardware (security key) or a secret saved on the user's | |
321 | smartphone. This prevents a remote user from gaining unauthorized access to an | |
322 | account, as even if they have the password, they will not have access to the | |
323 | physical object (second factor). | |
f9fcac51 | 324 | |
2f617a45 TL |
325 | .. image:: images/screenshots/pbs-gui-tfa-login.png |
326 | :align: right | |
327 | :alt: Add a new user | |
328 | ||
f9fcac51 TL |
329 | Available Second Factors |
330 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
331 | ||
207f763d DW |
332 | You can set up multiple second factors, in order to avoid a situation in which |
333 | losing your smartphone or security key locks you out of your account | |
334 | permanently. | |
f9fcac51 | 335 | |
207f763d DW |
336 | Proxmox Backup Server supports three different two-factor authentication |
337 | methods: | |
f9fcac51 TL |
338 | |
339 | * TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_). | |
207f763d | 340 | A short code derived from a shared secret and the current time, it changes |
f9fcac51 TL |
341 | every 30 seconds. |
342 | ||
343 | * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_). | |
344 | A general standard for authentication. It is implemented by various security | |
207f763d | 345 | devices, like hardware keys or trusted platform modules (TPM) from a computer |
f9fcac51 TL |
346 | or smart phone. |
347 | ||
348 | * Single use Recovery Keys. A list of keys which should either be printed out | |
207f763d DW |
349 | and locked in a secure place or saved digitally in an electronic vault. |
350 | Each key can be used only once. These are perfect for ensuring that you are | |
351 | not locked out, even if all of your other second factors are lost or corrupt. | |
f9fcac51 TL |
352 | |
353 | ||
354 | Setup | |
355 | ~~~~~ | |
356 | ||
357 | .. _user_tfa_setup_totp: | |
28eaff20 | 358 | |
f9fcac51 TL |
359 | TOTP |
360 | ^^^^ | |
2f617a45 TL |
361 | |
362 | .. image:: images/screenshots/pbs-gui-tfa-add-totp.png | |
363 | :align: right | |
364 | :alt: Add a new user | |
365 | ||
207f763d | 366 | There is no server setup required. Simply install a TOTP app on your |
f9fcac51 TL |
367 | smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the |
368 | Proxmox Backup Server web-interface to add a TOTP factor. | |
369 | ||
370 | .. _user_tfa_setup_webauthn: | |
28eaff20 | 371 | |
f9fcac51 TL |
372 | WebAuthn |
373 | ^^^^^^^^ | |
374 | ||
207f763d | 375 | For WebAuthn to work, you need to have two things: |
f9fcac51 | 376 | |
717ce406 | 377 | * A trusted HTTPS certificate (for example, by using `Let's Encrypt |
5bf9b0b0 DC |
378 | <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_). |
379 | While it probably works with an untrusted certificate, some browsers may warn | |
380 | or refuse WebAuthn operations if it is not trusted. | |
f9fcac51 | 381 | |
717ce406 DW |
382 | * Setup the WebAuthn configuration (see **Configuration -> Authentication** in |
383 | the Proxmox Backup Server web interface). This can be auto-filled in most | |
384 | setups. | |
f9fcac51 | 385 | |
207f763d | 386 | Once you have fulfilled both of these requirements, you can add a WebAuthn |
60589e60 DW |
387 | configuration in the **Two Factor Authentication** tab of the **Access Control** |
388 | panel. | |
f9fcac51 TL |
389 | |
390 | .. _user_tfa_setup_recovery_keys: | |
28eaff20 | 391 | |
f9fcac51 TL |
392 | Recovery Keys |
393 | ^^^^^^^^^^^^^ | |
394 | ||
2f617a45 TL |
395 | .. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png |
396 | :align: right | |
397 | :alt: Add a new user | |
398 | ||
207f763d | 399 | Recovery key codes do not need any preparation; you can simply create a set of |
60589e60 DW |
400 | recovery keys in the **Two Factor Authentication** tab of the **Access Control** |
401 | panel. | |
f9fcac51 TL |
402 | |
403 | .. note:: There can only be one set of single-use recovery keys per user at any | |
404 | time. | |
405 | ||
406 | TFA and Automated Access | |
407 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
408 | ||
207f763d | 409 | Two-factor authentication is only implemented for the web-interface. You should |
f9fcac51 | 410 | use :ref:`API Tokens <user_tokens>` for all other use cases, especially |
207f763d | 411 | non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE |
f9fcac51 | 412 | as a storage). |