Install it

You need OPNsense 26.7 or later. The library package is built for PHP 8.5, which OPNsense 26.7 uses.

Open a shell on the firewall as root. Log in with SSH, or select option 8 (Shell) at the console.

Run these four commands:

fetch -o /tmp/php85-webauthn.pkg "https://campbell-moore.com/downloads/os-webauthn/latest?role=dependency"
fetch -o /tmp/os-webauthn.pkg    "https://campbell-moore.com/downloads/os-webauthn/latest"
pkg add /tmp/php85-webauthn.pkg /tmp/os-webauthn.pkg
configctl webgui restart

Reload the web interface in your browser.

The plugin adds two items under System → Access:

2FA is where each user sets up their own passkey or one-time code.
2FA Settings is for administrators. It holds the settings for everyone and the list of enrolled passkeys.

The links always point to the current release, so the commands do not go out of date.

Why there are two files

The plugin and its library change at different times. Two packages let you update one without reinstalling the other.

php85-webauthn is the WebAuthn protocol library. It does the cryptography. It is a general-purpose PHP library that I did not write; I packaged it for the firewall. Without it, the plugin still installs, but it does not offer passkeys.
os-webauthn-devel is the plugin: the settings page, the enrolment flow and the sign-in screen.

The pkg add command above installs both files.

Set up a passkey

Open the web interface by its hostname. Browsers do not allow passkeys on an IP address.
Open System → Access → 2FA Settings, then the Passkeys tab.
Select Enable passkey sign-in, then select Save.
Open System → Access → 2FA, then the Passkey tab.
Type a name for the key, then select Register key.
Select Use the key now. The plugin saves the key only after this test sign-in works.

The login page now shows a passkey button next to the password form.

Set up one-time codes

Open System → Access → 2FA Settings. On the One-time codes tab, select Create it.
Open System → Access → 2FA. On the One-time code tab, select Generate.
Scan the QR code with your authenticator app or password manager.
Type the current code, then select Verify and save.
Make sure that every user who signs in has done steps 2 to 4.
Go back to 2FA Settings and select Require codes now.
Keep this session open. Sign in from a second browser to test.

The code has its own box on the login page, so a password manager can fill it. For sudo, SSH with a password and the console, type the code straight after the password, with no space. The Other ways in section of 2FA Settings sets which of these ask for a code. A passkey works only in the browser.

If something goes wrong

The 2FA items are not in the menu.

Make sure your account has the 2FA privileges. Administrators have them. For other users, add them in System → Access → Groups.
Run rm -f /var/lib/php/tmp/opnsense_menu_cache.xml /var/lib/php/tmp/opnsense_acl_cache.json, then reload the page.
If the items are still missing, run pkg info os-webauthn-devel. The output shows if the package is installed.

The passkey tab says passkeys are not available. You opened the web interface by IP address, or php85-webauthn is not installed.

You think you are locked out. The plugin never turns off password sign-in. Passkeys are added next to the password.

Caution: Require codes now makes a one-time code necessary. Do not select it until your code works in a second browser.

If a user loses their authenticator after codes are required, remove their second factor as root:

Open a shell on the firewall as root.
Run /usr/local/opnsense/scripts/webauthn/reset2fa.php remove username.

This removes the user's code and passkeys. Their password does not change. The audit log records each removal.

Remove it

Run pkg delete os-webauthn-devel.
Run configctl webgui restart.

Password sign-in works during and after the removal. The plugin keeps its replay counters in /var/db/webauthn, so a reinstall cannot replay an old code. To remove them too, run rm -rf /var/db/webauthn.

What it actually does

Signs you in with a passkey instead of a password typed into the firewall's login form. A passkey is a credential held in a security key, a phone or a password manager.

It also adds one-time codes that a password manager can fill. The stock implementation does not allow that.

The bit worth knowing

Auditing the existing one-time-password path while building this surfaced a timing weakness in OPNsense's own TOTP comparison. It was reported, and the hardening fix now ships in OPNsense core. So the audit improved the thing it was auditing, whether or not you ever install this.

Requirements and licence

OPNsense 26.7 or later.

The plugin is PolyForm Noncommercial 1.0.0. It is free for personal and non-commercial use. For commercial use, ask for a separate licence. The bundled WebAuthn library keeps its own terms.

os-webauthn