campbell-moore.com / projects
OPNsense plugin

os-webauthn

Passkeys and password-manager-friendly one-time codes for the OPNsense firewall, without an identity provider on the firewall itself.

Download 0.2 Donate ♦

Install it

Four lines, pasted into the firewall's shell (System → Diagnostics → Command Prompt, or SSH in as root). The URLs always point at the current build, so these lines do not go stale:

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

Then open System → Access → WebAuthn and enrol a key. That is the whole installation.

Why two files?

Because they are two different things with two different lifetimes, and bundling them would mean reinstalling one every time the other changes.

  • php85-webauthn is the WebAuthn protocol library — the code that does the cryptography. It is a general-purpose PHP library, not mine, packaged so the firewall can install it. It goes on first, because the plugin will not load without it.
  • os-webauthn-devel is the plugin itself: the settings page, the enrolment flow, the sign-in screen.

pkg add is given both files in one command above, in the right order, so you do not have to think about it.

If something goes wrong

The menu entry is not there. The web interface caches its menu; configctl webgui restart is the line that clears it. If it still is not there, pkg info os-webauthn-devel will say whether the package is actually installed.

You are locked out. You are not — passwords keep working. Passkeys are added alongside, never instead of, unless you turn the password off yourself. Enrol and test on a second browser before you do that.

Removing it: pkg delete os-webauthn-devel then configctl webgui restart. Nothing is left behind and password sign-in is unaffected throughout.

What it actually does

Signs you in with a passkey — a credential held in a security key, a phone, or a password manager — instead of typing a password into a firewall's login form. It also adds one-time codes that a password manager can fill, which the stock implementation does not allow.

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 25.7 or later. The plugin is PolyForm Noncommercial 1.0.0 — free for personal and non-commercial use; commercial use is a separate licence, just ask. The bundled WebAuthn library keeps its own terms.

Releases 1
0.2
2026-09-16

Passkey registration and sign-in, one-time codes a password manager can fill, and the packaging fixed so the plugin survives an OPNsense major upgrade. Install php85-webauthn first - or give pkg add both files at once, as the instructions above do.