How to Enable Two-Factor Authentication in Proxmox VE

Why Two-Factor Authentication Matters

The Proxmox VE web interface is the control plane for your entire virtualization infrastructure. If an attacker compromises a password through phishing, credential stuffing, or brute force, they gain full access to create, destroy, and modify virtual machines. Two-factor authentication (2FA) adds a second verification step that makes stolen passwords alone insufficient for access.

Proxmox VE supports several second-factor methods:

• TOTP (Time-based One-Time Password) – works with apps like Google Authenticator, Authy, or FreeOTP.
• WebAuthn – hardware security keys such as YubiKey or SoloKey.
• Recovery keys – one-time-use backup codes for emergency access.

This guide focuses on TOTP, which is the most widely used method and requires no additional hardware.

Setting Up TOTP via the Web GUI

Each user configures their own second factor. There is no global toggle that forces 2FA on everyone at once (though you can enforce it through TFA realm requirements, covered below).

Step 1: Log In and Open TFA Settings

Log in to the Proxmox web interface at https://your-proxmox-host:8006. Click your username in the top-right corner and select TFA (Two Factor Auth), or navigate to Datacenter > Permissions > Two Factor.

Step 2: Add a TOTP Key

Click Add and choose TOTP. Proxmox will display a QR code. Open your authenticator app and scan the QR code. Enter the six-digit code from the app to verify the setup, then provide a description (e.g., "Phone Authenticator") and click Add.

Step 3: Generate Recovery Keys

Immediately after adding TOTP, add a set of recovery keys. Click Add again and choose Recovery Keys. Proxmox will generate a list of single-use codes. Save these in a secure location such as a password manager or a printed sheet stored in a safe.

Never skip recovery keys. If you lose your phone or authenticator app, recovery keys are the only way to regain access without CLI intervention on the node itself.

Setting Up TOTP via the Command Line

You can manage TFA entirely from the shell using pveum. This is useful for scripted deployments or when you need to configure 2FA for users who cannot access the web GUI.

List Current TFA Configurations

# List all users with their TFA status
pveum user list

# View TFA entries for a specific user
pveum user tfa list user@pam

Add a TOTP Key for a User

# Generate a TOTP secret and add it to a user
# The secret will be displayed; the user must add it to their authenticator app
pveum user tfa add user@pam totp --description "CLI TOTP Setup"

# You can also specify a custom issuer and digits
pveum user tfa add user@pam totp \
    --description "Proxmox Auth" \
    --issuer "ProxmoxVE" \
    --digits 6

Generate Recovery Keys via CLI

# Add recovery keys for the user
pveum user tfa add user@pam recovery --description "Emergency Recovery Keys"

# The output will display the recovery codes - save them securely

Remove a TFA Entry

# List TFA entries to find the ID
pveum user tfa list user@pam

# Delete a specific TFA entry by its ID
pveum user tfa delete user@pam <tfa-id>

Enforcing 2FA for All Users in a Realm

To require 2FA for every user in a realm, you can configure the realm to mandate a second factor. Users who have not configured TFA will be prompted to do so on their next login.

# Require TOTP for all users in the pam realm
pveum realm modify pam --tfa type=totp

# Require TOTP for all users in a custom realm
pveum realm modify my-ldap-realm --tfa type=totp

# Remove the TFA requirement from a realm
pveum realm modify pam --delete tfa

When TFA is enforced at the realm level, users who log in without a configured second factor will see a setup dialog. They must complete TOTP registration before they can proceed.

Per-User Configuration and Multiple Devices

Proxmox allows each user to register multiple second factors. This is valuable for redundancy and for supporting different devices:

• Register TOTP on your primary phone.
• Register TOTP on a secondary device or tablet.
• Add a WebAuthn hardware key as a backup.
• Generate recovery keys for emergency scenarios.

At login, Proxmox presents all registered methods and the user chooses which one to use. If any single method is compromised, you can revoke it without losing access through the others.

Emergency Access: Bypassing 2FA from the CLI

If a user is locked out and has no recovery keys, a root administrator can remove their TFA configuration from the command line on the Proxmox node itself:

# SSH into the Proxmox node as root
ssh root@proxmox-node

# List the locked-out user's TFA entries
pveum user tfa list lockeduser@pam

# Delete all TFA entries for the user
pveum user tfa delete lockeduser@pam <tfa-id>

# The user can now log in with just their password
# Have them reconfigure 2FA immediately after regaining access

Monitoring TFA Status Remotely

Keeping track of which users have enabled 2FA is important for security audits. While the web GUI shows this information under Datacenter > Permissions > Two Factor, checking it regularly can be tedious. If you manage your Proxmox environment on the go, ProxmoxR lets you review user accounts and their authentication status from your mobile device, which is helpful when verifying that team members have completed their 2FA setup.

Best Practices

• Enforce 2FA at the realm level rather than relying on individual users to enable it voluntarily.
• Always generate recovery keys and store them separately from your authenticator device.
• Register at least two second-factor methods so you are not dependent on a single device.
• Use a time-synced authenticator app. TOTP depends on accurate clocks. If your Proxmox server or phone clock drifts, codes will fail. Ensure NTP is configured on your Proxmox nodes.
• Audit TFA enrollment regularly. Check that all users, especially those with administrative privileges, have 2FA enabled.
• Combine 2FA with strong passwords. Two-factor authentication is a second layer, not a replacement for good password hygiene.

Summary

Enabling two-factor authentication on Proxmox VE is one of the simplest and most effective security improvements you can make. Whether you configure it through the web GUI or automate it with pveum commands, the process takes only minutes per user. Enforce it at the realm level for consistent coverage, always create recovery keys, and register multiple devices for resilience. Your virtualization infrastructure is too important to protect with passwords alone.