MFA and TOTP

A strong password is necessary and insufficient. A credential that grants full administrative control of a firewall must be backed by a second factor. The factor can be a hardware token (YubiKey, Titan), a TOTP application on a smartphone, or a push-based authenticator. The choice for most OPNsense deployments is TOTP because it works offline, requires no external service to validate, and integrates with the authentication framework that OPNsense already exposes.

This lesson covers why MFA is mandatory for firewall administration, how to enable TOTP on the OPNsense GUI and SSH, when to introduce freeRADIUS for centralised MFA, and how to manage recovery codes so the offboarding flow works when an operator loses a device.

Why a password alone is insufficient

The argument is the same one the entire MFA industry has been making for a decade, and it is correct: passwords are stolen, reused, guessed, phished, keylogged, and dumped from breach databases. The OPNsense GUI accepts a password and grants full administrative control. If the password leaks, the firewall is compromised.

TOTP adds a second factor that the attacker does not have. The TOTP secret is stored on the operator device and is required in addition to the password. An attacker with the password but not the device cannot log in.

For firewall administration, the threat model is:

• Credential stuffing: passwords from public breach databases tried against the GUI.
• Phishing: an operator tricked into entering credentials on a fake login page.
• Keylogger malware on an operator workstation.
• Password reuse: the operator password on another site is breached and the same password is used on the firewall.

TOTP defeats the first three (the attacker does not have the TOTP secret) and slows the fourth (the attacker needs both the password and the device).

Enabling TOTP on the OPNsense GUI

OPNsense ships TOTP support in the core. The configuration:

1. Per-user TOTP enrolment. Each operator enrols their own TOTP secret on their account. The enrolment is under System → Access → Users → (user) → OTP. The user clicks “Generate”, the GUI displays a QR code, and the user scans it with their authenticator app (Google Authenticator, 1Password, Authy, Bitwarden).
2. TOTP validation on login. When TOTP is enabled, the login form requires the password AND a 6-digit code. The password goes in the password field; the code goes in the OTP field.
3. Clock drift tolerance. OPNsense accepts TOTP codes within a configurable window around the current time. The default is one step before and one step after, giving a 90-second tolerance for clock drift between the operator device and the firewall.

The verification step is to log in as the operator with a fresh TOTP code. If the login succeeds, the enrolment is correct.

TOTP for SSH

OPNsense supports TOTP for SSH via the OPNsense SSH daemon configuration. The setup:

1. Enable TOTP on the user account (same as for the GUI).
2. Under System → Settings → Administration, set the SSH service to require TOTP for the relevant users.
3. The operator connects with ssh operator@fw.example.com. The SSH client prompts for the password, then for the TOTP code.

The interactive nature of the SSH TOTP flow is a known friction point. Operators using ssh-agent for passwordless login find that the TOTP prompt breaks the agent flow. The typical solution is to use a hardware token (FIDO2) for SSH instead of TOTP — the key tap is interactive but the agent flow still works for password-less key auth.

$ ssh -o PreferredAuthentications=publickey,keyboard-interactive -o PubkeyAuthentication=no operator@fw.example.com

operator@fw.example.com's password: 
operator@fw.example.com's OTP code: 
Last login: Fri Aug 14 03:27:14 2026 from 10.255.100.50
OPNsense 25.x ...

freeRADIUS for centralised MFA

For estates with more than a handful of firewalls, the per-firewall TOTP configuration does not scale. The operator has to enrol on every firewall. Revocation requires touching every firewall. The audit trail is fragmented.

The solution is to centralise authentication through freeRADIUS. OPNsense ships the os-radius and freeRADIUS plugins for this. The architecture:

• One freeRADIUS server. The authoritative source of operator authentication. TOTP validation happens here.
• OPNsense as a RADIUS client. The firewall passes authentication requests to the RADIUS server. The RADIUS server returns accept or reject.
• Multi-factor flow. The operator enters their username and password on the GUI. OPNsense passes the credentials to RADIUS. RADIUS prompts for the TOTP code (the Access-Challenge response). The operator enters the code. RADIUS returns accept.

The freeRADIUS configuration uses the rlm_otp module for TOTP validation. The operator enrols once on the RADIUS server; the firewall sees only the authentication result.

Recovery codes

TOTP enrolment typically generates a small set of recovery codes (often 8–10 single-use codes) that the operator can use when their device is unavailable. The recovery code flow:

1. Generated at enrolment. The operator saves the recovery codes in a secure location (password manager, printed and stored in a safe) at enrolment time.
2. Used at login. When the TOTP device is unavailable, the operator enters a recovery code in place of the TOTP code.
3. Consumed. Each recovery code is single-use. After consumption, it cannot be used again.
4. Replaced. When recovery codes run low, the operator re-enrols and generates a new set. The old codes become invalid.

The operational trap is the operator who saves the recovery codes on the same device as the TOTP authenticator (e.g. both in the same password manager). When the device is lost, both the TOTP secret and the recovery codes are lost. The production discipline: recovery codes must be in a different location than the TOTP device. Common patterns:

• TOTP on smartphone. Recovery codes printed and stored in a physical safe.
• TOTP in a password manager. Recovery codes in a separate password manager, in a vault, or with a manager.
• TOTP on a hardware token. Recovery codes in a password manager or vault.

Offboarding when a device is lost

When an operator loses their device, the offboarding flow is:

1. The operator reports the loss to the security team.
2. The security team disables the operator TOTP enrolment on every firewall (or on the RADIUS server, if centralised).
3. The operator re-enrols with a new device.
4. The old TOTP secret is invalidated.

The window between report and re-enrolment is when the attacker can act. The discipline:

• The disable step happens first, before any conversation about replacement.
• The replacement device is set up in person or over a verified channel, not over email.
• Old recovery codes are revoked as part of the disable step.

Summary

• TOTP adds a “something you have” factor on top of the password. Mandatory for firewall administration.
• OPNsense ships TOTP support for the GUI. SSH TOTP is supported but interactive; consider FIDO2 hardware keys for the SSH flow.
• For multi-firewall estates, centralise via freeRADIUS. The production pattern includes a break-glass account for RADIUS failure scenarios.
• Recovery codes must be stored in a different location than the TOTP device.
• Offboarding: disable first, re-enrol second. Revoke old recovery codes as part of the disable.