Two-factor authentication and TOTP — the second factor that matters

A password is a single factor — something the operator knows. A second factor is something the operator has (a hardware token, a phone running an authenticator app) or something the operator is (a biometric). Two-factor authentication requires both factors to authenticate. A stolen password alone is not enough to log in; the attacker needs the second factor too.

This lesson covers how two-factor authentication works at the protocol level, how to enable TOTP (Time-Based One-Time Password, RFC 6238) on OPNsense, how to manage TOTP enrolment and recovery codes, and the operational discipline for rolling out 2FA across an operator fleet.

What two-factor authentication gives you

A password can be phished, guessed, leaked, or stolen from a breached database. Two-factor authentication makes a stolen password insufficient: the attacker also needs the second factor. The second factor is typically a hardware token or a phone running an authenticator app — something the attacker cannot get from a database breach.

The factors:

• Something you know: password, PIN, security question.
• Something you have: hardware token, phone with authenticator app, smart card.
• Something you are: fingerprint, face, iris.

Two-factor authentication combines two different factors. Password + security question is single-factor (both are “something you know”). Password + TOTP from a phone is two-factor (something you know + something you have).

How TOTP works

TOTP (Time-Based One-Time Password, RFC 6238) generates a six-digit code from a shared secret and the current time. The algorithm:

TOTP = HOTIP(K, T)
  where K is the shared secret
        T is floor((current_time - T0) / X)
        T0 is the Unix epoch (typically 0)
        X is the time step (typically 30 seconds)
        HOTIP is HMAC-based OTP (RFC 4226)

The server and the client both have the same shared secret. They both compute TOTP from the current time. The codes match. The code is valid for one time step (typically 30 seconds), then expires.

The enrolment:

1. The server generates a shared secret (typically 160 bits of random data, base32-encoded for human reading).
2. The server presents the secret to the operator as a QR code (or a base32 string for manual entry).
3. The operator scans the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.). The app stores the secret and starts generating TOTP codes.
4. The operator types a code from the app into the server to confirm enrolment.

After enrolment, every login requires the operator to type their password and a current TOTP code.

$ oathtool --totp --base32 "JBSWY3DPEHPK3PXP" -d 30

857163

Enabling TOTP on OPNsense

OPNsense supports TOTP as a second factor for the GUI. The configuration:

1. Open System → Access → Servers and add a TOTP server (the local TOTP validation).
2. Open System → Settings → Administration and enable Two-factor authentication for the GUI.
3. Each operator enrols individually: the operator logs in, OPNsense presents a QR code, the operator scans it with their authenticator app, the operator types a verification code to confirm enrolment.

For local accounts, the enrolment is straightforward. For LDAP/RADIUS/TACACS authenticated operators, the TOTP validation runs against the operator’s local TOTP secret, which must be configured per operator in the OPNsense user record (this is one of the reasons some estates run 2FA at the central identity server rather than per-firewall).

Recovery codes

When an operator loses access to their second factor (phone lost, hardware token broken, authenticator app reinstalled), the recovery path matters. OPNsense supports recovery codes:

1. At enrolment, OPNsense generates a set of one-time recovery codes (typically 10 codes).
2. The operator is expected to store these codes in a safe place (printed, in a password manager, in a sealed envelope).
3. If the operator loses their second factor, they can use a recovery code instead of a TOTP code. The recovery code is consumed (single-use).

Recovery codes are a back-up channel. They must be protected as carefully as the password. An attacker with a recovery code can authenticate as the operator, bypassing 2FA.

Operational rollout

Rolling out 2FA across an operator fleet is an operational project. The phases:

1. Pilot: enable 2FA for one or two senior operators. Validate the enrolment flow, the recovery code generation, and the day-to-day login experience.
2. Phased rollout: enable 2FA for a subset of the operator base. Communicate the timeline. Have support ready for operators who lose tokens.
3. Full enforcement: 2FA required for all operators with administrative access.

The communication matters. Operators who are not told that 2FA is being rolled out will be surprised by the enrolment prompt. Operators who are told but not given time to enrol will be locked out at the next login.

The support matters. An operator who loses their phone on a Friday evening needs a recovery path that does not require the on-call team to debug TOTP. The recovery codes cover this. The break-glass local admin account covers the case where recovery codes are also lost.

Failure modes of 2FA

The 2FA-enabled failure modes:

1. Time skew. The operator’s phone has a drifted clock that produces TOTP codes outside the server’s accepted window. Fix: correct the phone’s clock; configure the server’s accepted window to be tolerant.
2. Wrong secret enrolled. The operator scanned the wrong QR code or mistyped the base32 secret. Their codes do not match the server’s. Fix: re-enrol.
3. Lost device with no recovery codes. The operator has no second factor and no recovery code. Fix: break-glass local admin disables 2FA for the operator.
4. Authenticator app data lost. The operator reinstalled their phone and the authenticator app has no record of the secret. Fix: recovery codes; if none, break-glass.
5. Recovery code already used. The recovery code was consumed. The operator cannot reuse it. Fix: new recovery code, or break-glass.

Summary

• Two-factor authentication combines two different factors (something you know + something you have). A stolen password alone is not enough.
• TOTP generates six-digit codes from a shared secret and the current time. The server and the operator’s app both compute the same code.
• Enable TOTP on OPNsense via System → Settings → Administration. Operators enrol by scanning a QR code.
• Recovery codes are second-factor equivalents and must be protected accordingly. Have a documented recovery runbook.
• Local break-glass accounts remain essential: an operator who loses their second factor and recovery codes needs a way back in.