OATH(TOTP) Authentication

OATH(TOTP) Authentication

In order to use OATH (TOTP) two-factor authentication (2FA) in Proxmox VE you need to (in this order):

1. Ensure you have root or administrative access to your server and to editing the `/etc/pve/domains.cfg` file in case you need to revert back to PAM-only authentication
2. Open a shell session and generate an OATH key ID for each user
3. Add the user's key ID to its profile in the Proxmox GUI
4. Enable OATH (OTP) 2FA to secure a realm

WARNING: Do NOT enable 2FA authentication until you have completed the first 3 steps or you risk locking yourself out of your PVE server. At this time there is no way to enable 2FA on a per-user basis.

Below is a short procedure to set this up.

Generating a user OATH 2FA key ID

In order to configure your 2FA clients and the PVE user account to use OATH (TOTP) you need a user-generated key ID. Each user can do this via a shell access when logged in or the root user can do it for all users from a shell access.

You'll want to secure the key while it is traveling instead of sending it plaintext or obscured.

Text-only key ID generation for manual configuration

1. While logged in as root to your web UI, go to Server View > (your node - PVE in this example) > Shell
2. Generate the OATH key:

root@oathtest # oathkeygen
P6NDPDL6QDS7YFP4

You can generate keys for other users with the same command using su as follows:

root@oathtest # su alice
alice@oathtest $ oathkeygen
F5F4PHE22XGE4ZLA

The resulting key IDs can be used for PVE user account configuration and 2FA client configuration (mobile or else), see below.

Graphical (ANSI) QR code key ID generation for automatic configuration

You can generate the OATH key ID and generate a QR code in ANSI which will show up on your terminal by using this command (available when the qrencode package is installed):

clear && OATHKEYID=$(oathkeygen) && echo -e OATH key ID for $USER: $OATHKEYID && qrencode -t ANSIUTF8 -o - $(echo "otpauth://totp/PVE:$USER@"$(hostname --fqdn)"?secret=$OATHKEYID")

The resulting key ID (P6NDPDL6QDS7YFP4 in this example) will be used for PVE user account configuration and 2FA client configuration (mobile or else), see below.

You can also make this into a script for future use and save it under /opt/oath-qrencode.sh :

#!/bin/bash

clear

USERNAME=$USER
HOSTNAME=$(hostname --fqdn)
OATHKEY=$(oathkeygen)

echo -e  "OATH key ID for user $USERNAME@$HOSTNAME: $OATHKEY\r\r"

qrencode -t ANSIUTF8 -o - $(echo otpauth://totp/PVE:$USERNAME@$HOSTNAME?secret=$OATHKEY)

Finalizing 2FA configuration in your Proxmox user accounts and 2FA clients (mobile or else)

The next step is to associate the PVE user with the OATH key ID generated.

1. Go to Server View > Datacenter > Users > (click the user) > Edit
2. Add the key ID to the `Key IDs` field. Several IDs can be added to this fiels, separated by spaces
3. Click `OK` to save the user information

For 2FA client configuration on a mobile device (for example using AndOTP on Android), simply scan the QR code shown.

The OATH (OTP) key ID can also be used by itself to manually configure any compatible 2FA application.

Enabling or disabling OATH (OTP) 2FA to secure a realm

This example shows how to secure the PAM realm but any realm can have 2FA enabled.

Configuring PVE to enforce 2FA

Make sure that you are logged into the GUI as root@pam.

1. Go to Datacenter > Authentication, select a realm you want to secure and click Edit (or double-click the realm).
2. Select `OATH` in the `TFA` dropdown box. Three more fields will appear. The default values should be fine unless your client 2FA applications require other parameters.

Don't logout just yet unless you have completed users setup above first. OTP keys need to be configured for each user in Proxmox and in their 2FA clients. If you haven't done this for the root account you will effectively be locked-out from the web GUI. Acces can be restored by disabling 2FA (see below).

Disabling OATH 2FA authentication

If for any reason you wish to disable OATH TOTP 2FA authentication, you can do so by logging into your PVE server and editing the `/etc/pve/domains.cfg` file and removing this line:

        tfa type=oath