+WARNING: You need to ensure that the user is not allowed to edit
+the username setting themselves (on the Keycloak server).
+
+
+[[pveum_tfa_auth]]
+Two-Factor Authentication
+-------------------------
+
+There are two ways to use two-factor authentication:
+
+It can be required by the authentication realm, either via 'TOTP'
+(Time-based One-Time Password) or 'YubiKey OTP'. In this case, a newly
+created user needs to have their keys added immediately, as there is no way to
+log in without the second factor. In the case of 'TOTP', users can
+also change the 'TOTP' later on, provided they can log in first.
+
+Alternatively, users can choose to opt-in to two-factor authentication
+later on, even if the realm does not enforce it.
+
+Available Second Factors
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can set up multiple second factors, in order to avoid a situation in
+which losing your smartphone or security key locks you out of your
+account permanently.
+
+The following two-factor authentication methods are available in
+addition to realm-enforced TOTP and YubiKey OTP:
+
+* User configured TOTP
+ (https://en.wikipedia.org/wiki/Time-based_One-Time_Password[Time-based One-Time Password]).
+ A short code derived from a shared secret and the current time, it changes
+ every 30 seconds.
+* WebAuthn (https://en.wikipedia.org/wiki/WebAuthn[Web Authentication]).
+ A general standard for authentication. It is implemented by various
+ security devices, like hardware keys or trusted platform modules (TPM)
+ from a computer or smart phone.
+* Single use Recovery Keys. A list of keys which should either be
+ printed out and locked in a secure place or saved digitally in an
+ electronic vault. Each key can be used only once. These are perfect for
+ ensuring that you are not locked out, even if all of your other second
+ factors are lost or corrupt.
+
+Before WebAuthn was supported, U2F could be setup by the user. Existing
+U2F factors can still be used, but it is recommended to switch to
+WebAuthn, once it is configured on the server.
+
+Realm Enforced Two-Factor Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This can be done by selecting one of the available methods via the
+'TFA' dropdown box when adding or editing an Authentication Realm.
+When a realm has TFA enabled, it becomes a requirement, and only users
+with configured TFA will be able to log in.
+
+Currently there are two methods available:
+
+Time-based OATH (TOTP):: This uses the standard HMAC-SHA1 algorithm,
+where the current time is hashed with the user's configured key. The
+time step and password length parameters are configurable.
++
+A user can have multiple keys configured (separated by spaces), and the keys
+can be specified in Base32 (RFC3548) or hexadecimal notation.
++
+{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,
+FreeOTP, andOTP or similar applications.
+
+YubiKey OTP::
+For authenticating via a YubiKey a Yubico API ID, API KEY and validation
+server URL must be configured, and users must have a YubiKey available. In
+order to get the key ID from a YubiKey, you can trigger the YubiKey once
+after connecting it via USB, and copy the first 12 characters of the typed
+password into the user's 'Key IDs' field.
+
+Please refer to the https://developers.yubico.com/OTP/[YubiKey OTP]
+documentation for how to use the
+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_user_configured_totp]]
+User Configured TOTP Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can choose to enable 'TOTP' or 'WebAuthn' as a second factor on login, via
+the 'TFA' button in the user list (unless the realm enforces 'YubiKey OTP').
+
+Users can always add and use one time 'Recovery Keys'.
+
+[thumbnail="screenshot/gui-datacenter-two-factor.png"]
+
+After opening the 'TFA' window, the user is presented with a dialog to set up
+'TOTP' authentication. The 'Secret' field contains the key, which can be
+randomly generated via the 'Randomize' button. An optional 'Issuer Name' can be
+added to provide information to the 'TOTP' app about what the key belongs to.
+Most 'TOTP' apps will show the issuer name together with the corresponding
+'OTP' values. The username is also included in the QR code for the 'TOTP' app.
+
+After generating a key, a QR code will be displayed, which can be used with most
+OTP apps such as FreeOTP. The user then needs to verify the current user
+password (unless logged in as 'root'), as well as the ability to correctly use
+the 'TOTP' key, by typing the current 'OTP' value into the 'Verification Code'
+field and pressing the 'Apply' button.
+
+[[user_tfa_setup_totp]]
+=== TOTP
+
+[thumbnail="screenshot/pve-gui-tfa-add-totp.png"]
+
+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.
+
+[[user_tfa_setup_webauthn]]
+=== WebAuthn
+
+For WebAuthn to work, you need to have two things:
+
+* A trusted HTTPS certificate (for example, by using
+ https://pve.proxmox.com/wiki/Certificate_Management[Let's Encrypt]).
+ While it probably works with an untrusted certificate, some browsers may
+ warn or refuse WebAuthn operations if it is not trusted.
+* Setup the WebAuthn configuration (see *Datacenter -> Options ->
+ WebAuthn Settings* in the Proxmox VE web interface). This can be
+ auto-filled in most setups.
+
+Once you have fulfilled both of these requirements, you can add a WebAuthn
+configuration in the *Two Factor* panel under *Datacenter -> Permissions -> Two
+Factor*.
+
+[[user_tfa_setup_recovery_keys]]
+=== Recovery Keys
+
+[thumbnail="screenshot/pve-gui-tfa-add-recovery-keys.png"]
+
+Recovery key codes do not need any preparation; you can simply create a
+set of recovery keys in the *Two Factor* panel under *Datacenter -> Permissions
+-> Two Factor*.
+
+NOTE: There can only be one set of single-use recovery keys per user at any
+time.
+
+
+[[pveum_configure_webauthn]]
+Server Side Webauthn Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/gui-datacenter-webauthn-edit.png"]
+
+To allow users to use 'WebAuthn' authentication, it is necessaary to use a valid
+domain with a valid SSL certificate, otherwise some browsers may warn or refuse
+to authenticate altogether.
+
+NOTE: Changing the 'WebAuthn' configuration may render all existing 'WebAuthn'
+registrations unusable!
+
+This is done via `/etc/pve/datacenter.cfg`. For instance:
+
+----
+webauthn:
+rp=mypve.example.com,origin=https://mypve.example.com:8006,id=mypve.example.com
+----
+
+[[pveum_configure_u2f]]
+Server Side U2F Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+NOTE: It is recommended to use WebAuthn instead.
+
+To allow users to use 'U2F' authentication, it may be necessary to use a valid
+domain with a valid SSL certificate, otherwise, some browsers may print
+a warning or reject U2F usage altogether. Initially, an 'AppId'
+footnote:[AppId https://developers.yubico.com/U2F/App_ID.html]
+needs to be configured.
+
+NOTE: Changing the 'AppId' will render all existing 'U2F' registrations
+unusable!
+
+This is done via `/etc/pve/datacenter.cfg`. For instance:
+
+----
+u2f: appid=https://mypve.example.com:8006
+----
+
+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'.
+
+When using multiple nodes, it is best to have a separate `https` server
+providing an `appid.json`
+footnote:[Multi-facet apps: https://developers.yubico.com/U2F/App_ID.html]
+file, as it seems to be compatible with most
+browsers. If all nodes use subdomains of the same top level domain, it may be
+enough to use the TLD as 'AppId'. It should however be noted that some browsers
+may not accept this.
+
+NOTE: A bad 'AppId' will usually produce an error, but we have encountered
+situations when this does not happen, particularly when using a top level domain
+'AppId' for a node that is accessed via a subdomain in Chromium. For this reason
+it is recommended to test the configuration with multiple browsers, as changing
+the 'AppId' later will render existing 'U2F' registrations unusable.
+
+[[pveum_user_configured_u2f]]
+Activating U2F as a User
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable 'U2F' authentication, open the 'TFA' window's 'U2F' tab, type in the
+current password (unless logged in as root), and press the 'Register' button.
+If the server is set up correctly and the browser accepts the server's provided
+'AppId', a message will appear prompting the user to press the button on the
+'U2F' device (if it is a 'YubiKey', the button light should be toggling on and
+off steadily, roughly twice per second).
+
+Firefox users may need to enable 'security.webauth.u2f' via 'about:config'
+before they can use a 'U2F' token.
+
+[[pveum_permission_management]]
+Permission Management
+---------------------
+
+In order for a user to perform an action (such as listing, modifying or
+deleting parts of a VM's configuration), the user needs to have the
+appropriate permissions.
+
+{pve} uses a role and path based permission management system. An entry in
+the permissions table allows a user, group or token to take on a specific role
+when accessing an 'object' or 'path'. This means that such an access rule can
+be represented as a triple of '(path, user, role)', '(path, group,
+role)' or '(path, token, role)', with the role containing a set of allowed
+actions, and the path representing the target of these actions.
+
+
+[[pveum_roles]]
+Roles
+~~~~~
+
+A role is simply a list of privileges. Proxmox VE comes with a number
+of predefined roles, which satisfy most requirements.
+
+* `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`)
+* `PVEAuditor`: has read only access
+* `PVEDatastoreAdmin`: create and allocate backup space and templates
+* `PVEDatastoreUser`: allocate backup space and view storage
+* `PVEPoolAdmin`: allocate pools
+* `PVESysAdmin`: User ACLs, audit, system console and system logs
+* `PVETemplateUser`: view and clone templates
+* `PVEUserAdmin`: manage users
+* `PVEVMAdmin`: fully administer VMs
+* `PVEVMUser`: view, backup, configure CD-ROM, VM console, VM power management
+
+You can see the whole set of predefined roles in the GUI.
+
+You can add new roles via the GUI or the command line.
+
+[thumbnail="screenshot/gui-datacenter-role-add.png"]
+From the GUI, navigate to the 'Permissions -> Roles' tab from 'Datacenter' and
+click on the 'Create' button. There you can set a role name and select any
+desired privileges from the 'Privileges' drop-down menu.
+
+To add a role through the command line, you can use the 'pveum' CLI tool, for
+example:
+[source,bash]
+----
+pveum role add PVE_Power-only --privs "VM.PowerMgmt VM.Console"
+pveum role add Sys_Power-only --privs "Sys.PowerMgmt Sys.Console"
+----