docs/user-management.rst

   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
  18       authenticate as a Linux system user (users need to exist on the
  19       system).
  20
  21 :pbs: Proxmox Backup Server realm. This type stores hashed passwords in
  22       ``/etc/proxmox-backup/shadow.json``.
  23
  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:
  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
  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):
  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
  76 Newly created users do not have any permissions. Please read the :ref:`user_acl`
  77 section to learn how to set access permissions.
  78
  79 You can disable a user account by setting ``--enable`` to ``0``:
  80
  81 .. code-block:: console
  82
  83   # proxmox-backup-manager user update john@pbs --enable 0
  84
  85 Or completely remove a user with:
  86
  87 .. code-block:: console
  88
  89   # proxmox-backup-manager user remove john@pbs
  90
  91 .. _user_tokens:
  92
  93 API Tokens
  94 ----------
  95
  96 .. image:: images/screenshots/pbs-gui-apitoken-overview.png
  97   :align: right
  98   :alt: API Token Overview
  99
 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
 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
 112 the user password, respectively.
 113
 114 .. image:: images/screenshots/pbs-gui-apitoken-secret-value.png
 115   :align: right
 116   :alt: API secret value
 117
 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
 122 You can generate tokens from the GUI or by using ``proxmox-backup-manager``:
 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
 153
 154 .. _user_acl:
 155
 156 Access Control
 157 --------------
 158
 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.
 161
 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.
 168
 169 Privileges
 170 ~~~~~~~~~~
 171
 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.
 174
 175 We currently support the following privileges:
 176
 177 **Sys.Audit**
 178   Sys.Audit allows one to know about the system and its status.
 179
 180 **Sys.Modify**
 181   Sys.Modify allows one to modify system-level configuration and apply updates.
 182
 183 **Sys.PowerManagement**
 184   Sys.Modify allows one to to poweroff or reboot the system.
 185
 186 **Datastore.Audit**
 187   Datastore.Audit allows one to know about a datastore, including reading the
 188   configuration entry and listing its contents.
 189
 190 **Datastore.Allocate**
 191   Datastore.Allocate allows one to create or deleting datastores.
 192
 193 **Datastore.Modify**
 194   Datastore.Modify allows one to modify a datastore and its contents, and to
 195   create or delete namespaces inside a datastore.
 196
 197 **Datastore.Read**
 198   Datastore.Read allows one to read arbitrary backup contents, independent of
 199   the backup group owner.
 200
 201 **Datastore.Verify**
 202   Allows verifying the backup snapshots in a datastore.
 203
 204 **Datastore.Backup**
 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.
 208
 209 **Datastore.Prune**
 210   Datastore.Prune allows one to delete snapshots, but additionally requires
 211   backup ownership
 212
 213 **Permissions.Modify**
 214   Permissions.Modify allows one to modifying ACLs
 215
 216   .. note:: One can always configure privileges for their own API tokens, as
 217     they will clamped by the users privileges anyway.
 218
 219 **Remote.Audit**
 220   Remote.Audit allows one to read the remote and the sync configuration entries
 221
 222 **Remote.Modify**
 223   Remote.Modify allows one to modify the remote configuration
 224
 225 **Remote.Read**
 226   Remote.Read allows one to read data from a configured `Remote`
 227
 228 **Sys.Console**
 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.
 231
 232 **Tape.Audit**
 233   Tape.Audit allows one to read the configuration and status of tape drives,
 234   changers and backups
 235
 236 **Tape.Modify**
 237   Tape.Modify allows one to modify the configuration of tape drives, changers
 238   and backups
 239
 240 **Tape.Write**
 241   Tape.Write allows one to write to a tape media
 242
 243 **Tape.Read**
 244   Tape.Read allows one to read tape backup configuration and contents from a
 245   tape media
 246
 247 **Realm.Allocate**
 248   Realm.Allocate allows one to view, create, modify and delete authentication
 249   realms for users
 250
 251 Access Roles
 252 ~~~~~~~~~~~~
 253
 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.
 256
 257 Currently there are only built-in roles, that means, you cannot create your
 258 own, custom role.
 259
 260 The following roles exist:
 261
 262 **NoAccess**
 263   Disable Access - nothing is allowed.
 264
 265 **Admin**
 266   Can do anything, on the object path assigned.
 267
 268 **Audit**
 269   Can view the status and configuration of things, but is not allowed to change
 270   settings.
 271
 272 **DatastoreAdmin**
 273   Can do anything on *existing* datastores.
 274
 275 **DatastoreAudit**
 276   Can view datastore metrics, settings and list content. But is not allowed to
 277   read the actual data.
 278
 279 **DatastoreReader**
 280   Can inspect a datastore's or namespaces content and do restores.
 281
 282 **DatastoreBackup**
 283   Can backup and restore owned backups.
 284
 285 **DatastorePowerUser**
 286   Can backup, restore, and prune *owned* backups.
 287
 288 **RemoteAdmin**
 289   Can do anything on remotes.
 290
 291 **RemoteAudit**
 292   Can view remote settings.
 293
 294 **RemoteSyncOperator**
 295   Is allowed to read data from a remote.
 296
 297 **TapeAdmin**
 298   Can do anything related to tape backup
 299
 300 **TapeAudit**
 301   Can view tape related metrics, configuration and status
 302
 303 **TapeOperator**
 304   Can do tape backup and restore, but cannot change any configuration
 305
 306 **TapeReader**
 307   Can read and inspect tape configuration and media content
 308
 309 .. image:: images/screenshots/pbs-gui-user-management-add-user.png
 310   :align: right
 311   :alt: Add permissions for user
 312
 313 Access permission information is stored in ``/etc/proxmox-backup/acl.cfg``. The
 314 file contains 5 fields, separated using a colon (':') as a delimiter. A typical
 315 entry takes the form:
 316
 317 ``acl:1:/datastore:john@pbs:DatastoreBackup``
 318
 319 The data represented in each field is as follows:
 320
 321 #. ``acl`` identifier
 322 #. A ``1`` or ``0``, representing whether propagation is enabled or disabled,
 323    respectively
 324 #. The object on which the permission is set. This can be a specific object
 325    (single datastore, remote, etc.) or a top level object, which with
 326    propagation enabled, represents all children of the object also.
 327 #. The user(s)/token(s) for which the permission is set
 328 #. The role being set
 329
 330 You can manage permissions via **Configuration -> Access Control ->
 331 Permissions** in the web interface. Likewise, you can use the ``acl``
 332 subcommand to manage and monitor user permissions from the command line. For
 333 example, the command below will add the user ``john@pbs`` as a
 334 **DatastoreAdmin** for the datastore ``store1``, located at
 335 ``/backup/disk1/store1``:
 336
 337 .. code-block:: console
 338
 339   # proxmox-backup-manager acl update /datastore/store1 DatastoreAdmin --auth-id john@pbs
 340
 341 You can list the ACLs of each user/token using the following command:
 342
 343 .. code-block:: console
 344
 345    # proxmox-backup-manager acl list
 346    ┌──────────┬───────────────────┬───────────┬────────────────┐
 347    │ ugid     │ path              │ propagate │ roleid         │
 348    ╞══════════╪═══════════════════╪═══════════╪════════════════╡
 349    │ john@pbs │ /datastore/store1 │         1 │ DatastoreAdmin │
 350    └──────────┴───────────────────┴───────────┴────────────────┘
 351
 352 A single user/token can be assigned multiple permission sets for different
 353 datastores.
 354
 355 .. Note::
 356   Naming convention is important here. For datastores on the host,
 357   you must use the convention ``/datastore/{storename}``. For example, to set
 358   permissions for a datastore mounted at ``/mnt/backup/disk4/store2``, you would use
 359   ``/datastore/store2`` for the path. For remote stores, use the convention
 360   ``/remote/{remote}/{storename}``, where ``{remote}`` signifies the name of the
 361   remote (see `Remote` below) and ``{storename}`` is the name of the datastore on
 362   the remote.
 363
 364 API Token Permissions
 365 ~~~~~~~~~~~~~~~~~~~~~
 366
 367 API token permissions are calculated based on ACLs containing their ID,
 368 independently of those of their corresponding user. The resulting permission set
 369 on a given path is then intersected with that of the corresponding user.
 370
 371 In practice this means:
 372
 373 #. API tokens require their own ACL entries
 374 #. API tokens can never do more than their corresponding user
 375
 376 Effective Permissions
 377 ~~~~~~~~~~~~~~~~~~~~~
 378
 379 To calculate and display the effective permission set of a user or API token,
 380 you can use the ``proxmox-backup-manager user permission`` command:
 381
 382 .. code-block:: console
 383
 384   # proxmox-backup-manager user permissions john@pbs --path /datastore/store1
 385   Privileges with (*) have the propagate flag set
 386
 387   Path: /datastore/store1
 388   - Datastore.Audit (*)
 389   - Datastore.Backup (*)
 390   - Datastore.Modify (*)
 391   - Datastore.Prune (*)
 392   - Datastore.Read (*)
 393   - Datastore.Verify (*)
 394
 395   # proxmox-backup-manager acl update /datastore/store1 DatastoreBackup --auth-id 'john@pbs!client1'
 396   # proxmox-backup-manager user permissions 'john@pbs!client1' --path /datastore/store1
 397   Privileges with (*) have the propagate flag set
 398
 399   Path: /datastore/store1
 400   - Datastore.Backup (*)
 401
 402 .. _user_tfa:
 403
 404 Two-Factor Authentication
 405 -------------------------
 406
 407 Introduction
 408 ~~~~~~~~~~~~
 409
 410 With simple authentication, only a password (single factor) is required to
 411 successfully claim an identity (authenticate), for example, to be able to log in
 412 as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if
 413 the password gets leaked or stolen, anybody can use it to log in - even if they
 414 should not be allowed to do so.
 415
 416 With two-factor authentication (TFA), a user is asked for an additional factor
 417 to verify their authenticity. Rather than relying on something only the user
 418 knows (a password), this extra factor requires something only the user has, for
 419 example, a piece of hardware (security key) or a secret saved on the user's
 420 smartphone. This prevents a remote user from gaining unauthorized access to an
 421 account, as even if they have the password, they will not have access to the
 422 physical object (second factor).
 423
 424 .. image:: images/screenshots/pbs-gui-tfa-login.png
 425   :align: right
 426   :alt: Add a new user
 427
 428 Available Second Factors
 429 ~~~~~~~~~~~~~~~~~~~~~~~~
 430
 431 You can set up multiple second factors, in order to avoid a situation in which
 432 losing your smartphone or security key locks you out of your account
 433 permanently.
 434
 435 Proxmox Backup Server supports three different two-factor authentication
 436 methods:
 437
 438 * TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_).
 439   A short code derived from a shared secret and the current time, it changes
 440   every 30 seconds.
 441
 442 * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
 443   A general standard for authentication. It is implemented by various security
 444   devices, like hardware keys or trusted platform modules (TPM) from a computer
 445   or smart phone.
 446
 447 * Single use Recovery Keys. A list of keys which should either be printed out
 448   and locked in a secure place or saved digitally in an electronic vault.
 449   Each key can be used only once. These are perfect for ensuring that you are
 450   not locked out, even if all of your other second factors are lost or corrupt.
 451
 452
 453 Setup
 454 ~~~~~
 455
 456 .. _user_tfa_setup_totp:
 457
 458 TOTP
 459 ^^^^
 460
 461 .. image:: images/screenshots/pbs-gui-tfa-add-totp.png
 462   :align: right
 463   :alt: Add a new user
 464
 465 There is no server setup required. Simply install a TOTP app on your
 466 smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
 467 Proxmox Backup Server web-interface to add a TOTP factor.
 468
 469 .. _user_tfa_setup_webauthn:
 470
 471 WebAuthn
 472 ^^^^^^^^
 473
 474 For WebAuthn to work, you need to have two things:
 475
 476 * A trusted HTTPS certificate (for example, by using `Let's Encrypt
 477   <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_).
 478   While it probably works with an untrusted certificate, some browsers may warn
 479   or refuse WebAuthn operations if it is not trusted.
 480
 481 * Setup the WebAuthn configuration (see **Configuration -> Authentication** in
 482   the Proxmox Backup Server web interface). This can be auto-filled in most
 483   setups.
 484
 485 Once you have fulfilled both of these requirements, you can add a WebAuthn
 486 configuration in the **Two Factor Authentication** tab of the **Access Control**
 487 panel.
 488
 489 .. _user_tfa_setup_recovery_keys:
 490
 491 Recovery Keys
 492 ^^^^^^^^^^^^^
 493
 494 .. image:: images/screenshots/pbs-gui-tfa-add-recovery-keys.png
 495   :align: right
 496   :alt: Add a new user
 497
 498 Recovery key codes do not need any preparation; you can simply create a set of
 499 recovery keys in the **Two Factor Authentication** tab of the **Access Control**
 500 panel.
 501
 502 .. note:: There can only be one set of single-use recovery keys per user at any
 503  time.
 504
 505 TFA and Automated Access
 506 ~~~~~~~~~~~~~~~~~~~~~~~~
 507
 508 Two-factor authentication is only implemented for the web-interface. You should
 509 use :ref:`API Tokens <user_tokens>` for all other use cases, especially
 510 non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE
 511 as a storage).