OpenVPN MFA with client certificates and Google Authenticator

Use an independent console and a fresh sudo-capable VM, never paste these creation steps over an existing VPN. Confirm 192.0.2.40 is assigned locally and UDP 11940 is unused. The hostname must resolve to the public ingress, which may differ from this local address. Stop for an existing account academyvpn, interface tun-mfa, directory /srv/academy-openvpn-mfa, PAM service or unit academy-mfa. Review parent directories for symlinks before proceeding.

The time synchronization result must be yes and the phone must use automatic accurate time. Keep the existing NTP provider; repair it through its owner rather than installing a second daemon. Do not change host time to test an OTP. Apply only the pilot UDP rule and restricted tunnel INPUT access through the firewall owner; never flush or replace a firewall.

set -eu
cat /etc/os-release
test "$(ps -p 1 -o comm=)" = systemd
ip -br address
ip route show table all
sudo ss -lunp
getent passwd 'academyvpn' && exit 1 || test "$?" = 2
for path in '/srv/academy-openvpn-mfa' '/etc/pam.d/academy-mfa' '/etc/systemd/system/academy-mfa.service'; do
  test ! -e "$path" && test ! -L "$path"
done
ip link show 'tun-mfa' >/dev/null 2>&1 && exit 1 || test "$?" = 1
timedatectl status
timedatectl show -p NTPSynchronized --value

Use distribution packages and their security updates, not a one-line installer. Ubuntu 26.10 is the reviewed current stable default, supported through July 2027; 26.04/24.04 LTS are longer-lived alternatives. Debian 13 is stable; Debian 12 is in LTS with package/architecture coverage to check. The recipe targets OpenVPN 2.6-compatible community configuration, not Access Server or every GUI client. Record installed candidates; do not pin a stale upstream version.

Only documented OS paths are offered. The actual runtime fixture used Ubuntu 24.04 packages; this does not establish a booted installation on every listed release.

set -eu
. /etc/os-release
test "$VERSION_CODENAME" = 'stonking'
sudo apt-get update
apt-cache policy openvpn libpam-google-authenticator python3
sudo apt-get install --no-install-recommends openvpn libpam-google-authenticator python3 openssl ca-certificates nano
openvpn --version | head -n 2
dpkg-query -W openvpn libpam-google-authenticator python3

This guarded creation refuses existing paths/accounts and symlink parents. Review before running; a partial failure leaves evidence to inspect, not an invitation to rerun blindly. academyvpn is a new locked, non-login OS identity; it receives no shell or sudo permission. The auth-pam library is discovered from the package list, resolved to one real root-owned non-writable target and linked locally; multiarch paths are not guessed.

The temporary auth directory is accessible only to the reduced OpenVPN UID. The packaged PAM helper remains privileged through its split-process model and can access the personal seed without making it readable by nobody. Do not add chroot here or replace the packaged plugin with an unrelated library.

sudo python3 - <<'PY'
import os, pathlib, pwd, subprocess
root=pathlib.Path('/srv/academy-openvpn-mfa')
assert root.is_absolute()
for p in [root, *root.parents]:
    assert not p.is_symlink(), 'Symlink path refused'
assert not root.exists(), 'Existing root refused'
for p in ['/etc/pam.d/academy-mfa','/etc/systemd/system/academy-mfa.service']:
    assert not os.path.lexists(p), 'Existing service refused'
try:
    pwd.getpwnam('academyvpn')
except KeyError:
    pass
else:
    raise SystemExit('Existing user refused')
root.mkdir(mode=0o755)
os.chmod(root,0o755)
for name,mode in [('pki',0o700),('users',0o755),('auth-tmp',0o700)]:
    (root/name).mkdir(mode=mode)
    os.chmod(root/name,mode)
subprocess.run(['useradd','--system','--user-group','--home-dir',str(root/'users/academyvpn'),'--create-home','--shell','/usr/sbin/nologin','academyvpn'],check=True)
u=pwd.getpwnam('academyvpn')
os.chmod(root/'users/academyvpn',0o700)
os.chown(root/'users/academyvpn',u.pw_uid,u.pw_gid)
n=pwd.getpwnam('nobody')
os.chown(root/'auth-tmp',n.pw_uid,n.pw_gid)
paths=[p for p in subprocess.check_output(['dpkg','-L','openvpn'],text=True).splitlines() if p.endswith('/openvpn-plugin-auth-pam.so') and pathlib.Path(p).is_file()]
targets={pathlib.Path(p).resolve() for p in paths}
assert len(targets)==1, 'Ambiguous/missing package plugin'
plugin=next(iter(targets))
assert plugin.stat().st_uid==0 and not plugin.stat().st_mode & 0o022
(root/'auth-pam.so').symlink_to(plugin)
print('Dedicated account/tree created; packaged plugin:',plugin)
PY

Run only in a private unrecorded terminal attended by the actual user. The command is interactive and intentionally reveals a QR/seed and recovery codes: never run it through this page, screen sharing, saved command output or a logging automation. Check that the home has no existing seed, then enroll Google Authenticator or another compatible TOTP app. Choose time-based tokens, disallow reuse, a small three-code window and three attempts per30seconds. The flags set those choices; confirm saving the file after comparing the app.

Do not follow an enrollment URL that sends the seed to an external QR service. Keep emergency codes offline and private, separate from the certificate and phone. Never put a seed, QR, OTP or recovery code in reader configuration, source JSON, screenshots or support logs. One identity gets one unique seed; administrators must not distribute a shared seed.

set -eu
sudo test ! -e '/srv/academy-openvpn-mfa/users/academyvpn/.google_authenticator'
sudo test ! -L '/srv/academy-openvpn-mfa/users/academyvpn/.google_authenticator'
sudo -H -u 'academyvpn' google-authenticator -t -d -w 3 -r 3 -R 30
sudo chmod 0600 '/srv/academy-openvpn-mfa/users/academyvpn/.google_authenticator'
sudo stat -c '%U %a %n' '/srv/academy-openvpn-mfa/users/academyvpn/.google_authenticator'