protocol. It allows clients to verify the identity of the user, based on
authentication performed by an external authorization server.
+[[user-realms-pam]]
Linux PAM Standard Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
authentication realm.
+[[user-realms-pve]]
{pve} Authentication Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~
required to set a password for this type of user upon creation.
+[[user-realms-ldap]]
LDAP
~~~~
be carried out automatically with <<pveum_ldap_sync, syncing>>.
+[[user-realms-ad]]
Microsoft Active Directory (AD)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* `Port` (`port`): The port that the Microsoft AD server listens on
+
+NOTE: Microsoft AD normally checks values like usernames without case
+sensitivity. To make {pve} do the same, you can disable the default
+`case-sensitive` option by editing the realm in the web UI, or using the CLI
+(change the `ID` with the realm ID):
+`pveum realm modify ID --case-sensitive 0`
+
[[pveum_ldap_sync]]
Syncing LDAP-Based Realms
~~~~~~~~~~~~~~~~~~~~~~~~~
* `Preview` (`dry-run`): No data is written to the config. This is useful if you
want to see which users and groups would get synced to the `user.cfg`.
+[[pveum_ldap_reserved_characters]]
+Reserved characters
+^^^^^^^^^^^^^^^^^^^
+
+Certain characters are reserved (see https://www.ietf.org/rfc/rfc2253.txt[RFC2253]) and cannot be
+easily used in attribute values in DNs without being escaped properly.
+
+Following characters need escaping:
+
+* Space ( ) at the beginning or end
+* Number sign (`#`) at the beginning
+* Comma (`,`)
+* Plus sign (`+`)
+* Double quote (`"`)
+* Forward slashes (`/`)
+* Angle brackets (`<>`)
+* Semicolon (`;`)
+* Equals sign (`=`)
+
+To use such characters in DNs, surround the attribute value in double quotes.
+For example, to bind with a user with the CN (Common Name) `Example, User`, use
+`CN="Example, User",OU=people,DC=example,DC=com` as value for `bind_dn`.
+
+This applies to the `base_dn`, `bind_dn`, and `group_dn` attributes.
+
+NOTE: Users with colons and forward slashes cannot be synced since these are
+reserved characters in usernames.
[[pveum_openid]]
OpenID Connect
your information:
----
-pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/auth/realms/your-realm --client-id XXX --username-claim username
+pveum realm add myrealm2 --type openid --issuer-url https://your.server:8080/realms/your-realm --client-id XXX --username-claim username
----
Using `--username-claim username` enables simple usernames on the
+
{pve} provides a key generation tool (`oathkeygen`) which prints out a random
key in Base32 notation, that can be used directly with various OTP tools, such
-as the `oathtool` command line tool, or on Android Google Authenticator,
+as the `oathtool` command-line tool, or on Android Google Authenticator,
FreeOTP, andOTP or similar applications.
YubiKey OTP::
https://www.yubico.com/products/services-software/yubicloud/[YubiCloud] or
https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/[host your own verification server].
+[[pveum_tfa_lockout]]
+Limits and Lockout of Two-Factor Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A second factor is meant to protect users if their password is somehow leaked
+or guessed. However, some factors could still be broken by brute force. For
+this reason, users will be locked out after too many failed 2nd factor login
+attempts.
+
+For TOTP, 8 failed attempts will disable the user's TOTP factors. They are
+unlocked when logging in with a recovery key. If TOTP was the only available
+factor, admin intervention is required, and it is highly recommended to require
+the user to change their password immediately.
+
+Since FIDO2/Webauthn and recovery keys are less susceptible to brute force
+attacks, the limit there is higher (100 tries), but all second factors are
+blocked for an hour when exceeded.
+
+An admin can unlock a user's Two-Factor Authentication at any time via the user
+list in the UI or the command line:
+
+[source,bash]
+----
+ pveum user tfa unlock joe@pve
+----
+
[[pveum_user_configured_totp]]
User Configured TOTP Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is no server setup required. Simply install a TOTP app on your
smartphone (for example, https://freeotp.github.io/[FreeOTP]) and use
-the Proxmox Backup Server web-interface to add a TOTP factor.
+the {pve} web interface to add a TOTP factor.
[[user_tfa_setup_webauthn]]
=== WebAuthn
u2f: appid=https://mypve.example.com:8006
----
-For a single node, the 'AppId' can simply be the address of the web-interface,
+For a single node, the 'AppId' can simply be the address of the web interface,
exactly as it is used in the browser, including the 'https://' and the port, as
shown above. Please note that some browsers may be more strict than others when
matching 'AppIds'.
* `Administrator`: has full privileges
* `NoAccess`: has no privileges (used to forbid access)
-* `PVEAdmin`: can do most tasks, but has no rights to modify system settings (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`)
+* `PVEAdmin`: can do most tasks, but has no rights to modify system settings
+ (`Sys.PowerMgmt`, `Sys.Modify`, `Realm.Allocate`) or permissions
+ (`Permissions.Modify`)
* `PVEAuditor`: has read only access
* `PVEDatastoreAdmin`: create and allocate backup space and templates
* `PVEDatastoreUser`: allocate backup space and view storage
+* `PVEMappingAdmin`: manage resource mappings
+* `PVEMappingUser`: view and use resource mappings
* `PVEPoolAdmin`: allocate pools
-* `PVESysAdmin`: User ACLs, audit, system console and system logs
+* `PVEPoolUser`: view pools
+* `PVESDNAdmin`: manage SDN configuration
+* `PVESDNUser`: access to bridges/vnets
+* `PVESysAdmin`: audit, system console and system logs
* `PVETemplateUser`: view and clone templates
* `PVEUserAdmin`: manage users
* `PVEVMAdmin`: fully administer VMs
example:
[source,bash]
----
-pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
+pveum role add VM_Power-only --privs "VM.PowerMgmt VM.Console"
pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
----
+NOTE: Roles starting with `PVE` are always builtin, custom roles are not
+allowed use this reserved prefix.
Privileges
~~~~~~~~~~
Node / System related privileges::
-* `Permissions.Modify`: modify access permissions
-* `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...)
-* `Sys.Console`: console access to node
-* `Sys.Syslog`: view syslog
-* `Sys.Audit`: view node status/config, Corosync cluster config, and HA config
-* `Sys.Modify`: create/modify/remove node network parameters
-* `Sys.Incoming`: allow incoming data streams from other clusters (experimental)
* `Group.Allocate`: create/modify/remove groups
+* `Mapping.Audit`: view resource mappings
+* `Mapping.Modify`: manage resource mappings
+* `Mapping.Use`: use resource mappings
+* `Permissions.Modify`: modify access permissions
* `Pool.Allocate`: create/modify/remove a pool
* `Pool.Audit`: view a pool
-* `Realm.Allocate`: create/modify/remove authentication realms
* `Realm.AllocateUser`: assign user to a realm
+* `Realm.Allocate`: create/modify/remove authentication realms
+* `SDN.Allocate`: manage SDN configuration
+* `SDN.Audit`: view SDN configuration
+* `Sys.Audit`: view node status/config, Corosync cluster config, and HA config
+* `Sys.Console`: console access to node
+* `Sys.Incoming`: allow incoming data streams from other clusters (experimental)
+* `Sys.Modify`: create/modify/remove node network parameters
+* `Sys.PowerMgmt`: node power management (start, stop, reset, shutdown, ...)
+* `Sys.Syslog`: view syslog
* `User.Modify`: create/modify/remove user access and details.
Virtual machine related privileges::
+* `SDN.Use`: access SDN vnets and local network bridges
* `VM.Allocate`: create/remove VM on a server
-* `VM.Migrate`: migrate VM to alternate server on cluster
-* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
-* `VM.Console`: console access to VM
-* `VM.Monitor`: access to VM monitor (kvm)
-* `VM.Backup`: backup/restore VMs
* `VM.Audit`: view VM config
+* `VM.Backup`: backup/restore VMs
* `VM.Clone`: clone/copy a VM
-* `VM.Config.Disk`: add/modify/remove disks
* `VM.Config.CDROM`: eject/change CD-ROM
* `VM.Config.CPU`: modify CPU settings
+* `VM.Config.Cloudinit`: modify Cloud-init parameters
+* `VM.Config.Disk`: add/modify/remove disks
+* `VM.Config.HWType`: modify emulated hardware types
* `VM.Config.Memory`: modify memory settings
* `VM.Config.Network`: add/modify/remove network devices
-* `VM.Config.HWType`: modify emulated hardware types
* `VM.Config.Options`: modify any other VM configuration
+* `VM.Console`: console access to VM
+* `VM.Migrate`: migrate VM to alternate server on cluster
+* `VM.Monitor`: access to VM monitor (kvm)
+* `VM.PowerMgmt`: power management (start, stop, reset, shutdown, ...)
+* `VM.Snapshot.Rollback`: rollback VM to one of its snapshots
* `VM.Snapshot`: create/delete VM snapshots
Storage related privileges::
* `Datastore.AllocateTemplate`: allocate/upload templates and ISO images
* `Datastore.Audit`: view/browse a datastore
+WARNING: Both `Permissions.Modify` and `Sys.Modify` should be handled with
+care, as they allow modifying aspects of the system and its configuration that
+are dangerous or sensitive.
+
+WARNING: Carefully read the section about inheritance below to understand how
+assigned roles (and their privileges) are propagated along the ACL tree.
Objects and Paths
~~~~~~~~~~~~~~~~~
* Permissions for individual users always replace group permissions.
* Permissions for groups apply when the user is member of that group.
* Permissions on deeper levels replace those inherited from an upper level.
+* `NoAccess` cancels all other roles on a given path.
Additionally, privilege separated tokens can never have permissions on any
given path that their associated user does not have.
`Permissions.Modify` privilege or,
depending on the path, the following privileges as a possible substitute:
+
-* `/storage/...`: additionally requires 'Datastore.Allocate`
-* `/vms/...`: additionally requires 'VM.Allocate`
-* `/pool/...`: additionally requires 'Pool.Allocate`
+* `/storage/...`: requires 'Datastore.Allocate`
+* `/vms/...`: requires 'VM.Allocate`
+* `/pool/...`: requires 'Pool.Allocate`
++
+If the path is empty, `Permissions.Modify` on `/access` is required.
+
-If the path is empty, `Permission.Modify` on `/access` is required.
+If the user does not have the `Permissions.Modify` privilege, they can only
+delegate subsets of their own privileges on the given path (e.g., a user with
+`PVEVMAdmin` could assign `PVEVMUser`, but not `PVEAdmin`).
-Command Line Tool
+Command-line Tool
-----------------
Most users will simply use the GUI to manage users. But there is also
-a fully featured command line tool called `pveum` (short for ``**P**roxmox
-**VE** **U**ser **M**anager''). Please note that all Proxmox VE command
-line tools are wrappers around the API, so you can also access those
+a fully featured command-line tool called `pveum` (short for ``**P**roxmox
+**VE** **U**ser **M**anager''). Please note that all Proxmox VE command-line
+tools are wrappers around the API, so you can also access those
functions through the REST API.
Here are some simple usage examples. To show help, type:
[source,bash]
+----
pveum
+----
or (to show detailed help about a specific command)
[source,bash]
+----
pveum help user add
+----
Create a new user:
[source,bash]
+----
pveum user add testuser@pve -comment "Just a test"
+----
Set or change the password (not all realms support this):
[source,bash]
+----
pveum passwd testuser@pve
+----
Disable a user:
[source,bash]
+----
pveum user modify testuser@pve -enable 0
+----
Create a new group:
[source,bash]
+----
pveum group add testgroup
+----
Create a new role:
[source,bash]
+----
pveum role add PVE_Power-only -privs "VM.PowerMgmt VM.Console"
+----
Real World Examples
To do this, first define the group:
[source,bash]
+----
pveum group add admin -comment "System Administrators"
+----
Then assign the role:
[source,bash]
+----
pveum acl modify / -group admin -role Administrator
+----
Finally, you can add users to the new 'admin' group:
[source,bash]
+----
pveum user modify testuser@pve -group admin
+----
Auditors
Example 1: Allow user `joe@pve` to see everything
[source,bash]
+----
pveum acl modify / -user joe@pve -role PVEAuditor
+----
Example 2: Allow user `joe@pve` to see all virtual machines
[source,bash]
+----
pveum acl modify /vms -user joe@pve -role PVEAuditor
+----
Delegate User Management
that with:
[source,bash]
+----
pveum acl modify /access -user joe@pve -role PVEUserAdmin
+----
User `joe@pve` can now add and remove users, and change other user attributes,
such as passwords. This is a very powerful role, and you most
are members of group `customers`:
[source,bash]
+----
pveum acl modify /access/realm/pve -user joe@pve -role PVEUserAdmin
pveum acl modify /access/groups/customers -user joe@pve -role PVEUserAdmin
+----
NOTE: The user is able to add other users, but only if they are
members of the group `customers` and within the realm `pve`.
Give the user `joe@pve` the role PVEVMAdmin on all VMs:
[source,bash]
+----
pveum acl modify /vms -user joe@pve -role PVEVMAdmin
+----
Add a new API token with separate privileges, which is only allowed to view VM
information (for example, for monitoring purposes):
[source,bash]
+----
pveum user token add joe@pve monitoring -privsep 1
pveum acl modify /vms -token 'joe@pve!monitoring' -role PVEAuditor
+----
Verify the permissions of the user and token:
[source,bash]
+----
pveum user permissions joe@pve
pveum user token permissions joe@pve monitoring
+----
Resource Pools
~~~~~~~~~~~~~~
department. First, create a group:
[source,bash]
+----
pveum group add developers -comment "Our software developers"
+----
Now we create a new user which is a member of that group:
[source,bash]
+----
pveum user add developer1@pve -group developers -password
+----
NOTE: The "-password" parameter will prompt you for a password
Then we create a resource pool for our development department to use:
[source,bash]
+----
pveum pool add dev-pool --comment "IT development pool"
+----
Finally, we can assign permissions to that pool:
[source,bash]
+----
pveum acl modify /pool/dev-pool/ -group developers -role PVEAdmin
+----
Our software developers can now administer the resources assigned to
that pool.
projects / pve-docs.git / blobdiff