OPNsense Captive Portal Setup: A Step-by-Step Guide

OPNsense's built-in Captive Portal puts guests through a login page before they reach the internet. In this guide we set up a captive portal with Captivo on OPNsense step by step — one that shows your own branding, verifies guests by SMS and keeps compliant connection records.

Requirements

• A working OPNsense installation
• An interface carrying guest traffic (usually a separate LAN/VLAN)
• A Captivo account (portal design and RADIUS details come from here)

How it differs from pfSense

The logic is the same, but OPNsense differs from pfSense in two places — and Captivo handles both for you:

• Login method: OPNsense authenticates through its own captive portal API (the portal page calls OPNsense's logon endpoint instead of posting a hidden form). Captivo's OPNsense template is generated accordingly.
• Bandwidth limiting: OPNsense does not use the WISPr bandwidth values from RADIUS; rate limits are defined box-side with the Traffic Shaper.

1. Create a Captive Portal zone

Under Services → Captive Portal → Administration, add a new zone and select your guest interface. Enable the zone.

2. Add the RADIUS server and attach it to the zone

Captivo's RADIUS server handles verification:

1. Under System → Access → Servers, add a new RADIUSserver: the Captivo RADIUS address, the shared secret from your dashboard, and authentication port 1812.
2. In the Captive Portal zone settings, select this RADIUS server under Authentication.
3. In Captivo, add your OPNsense device as a NAS client (IP + the same shared secret).

3. Allow Captivo in the allowed addresses

Before a guest is verified, the portal page must reach Captivo (logo, verification, SMS). Create a firewall alias (host type, FQDN) containing the Captivo and SMS provider domains, and add it to the zone's allowed addresses so those hosts are reachable pre-authentication.

4. Upload the branded template

1. In Captivo, download the template package from Settings → Portal → Templates → OPNsense.
2. In OPNsense, upload it under Services → Captive Portal → Administration → Templates.
3. In the zone settings, select your uploaded Captivo template as the Template and apply the changes.

5. Bandwidth limiting — Traffic Shaper

To cap per-guest bandwidth, define it under Firewall → Shaper: create a Pipe/Queue with download/upload limits for the guest interface and match it with a rule. (On pfSense this comes from RADIUS WISPr; on OPNsense it is done box-side.)

How it works

When a guest connects, OPNsense shows your branded login page. The guest enters their phone number, the portal verifies it against Captivo's API, then sends the returned username and password to OPNsense's captive portal logon endpoint. OPNsense checks it against Captivo RADIUS; on success the guest reaches the internet and the connection is recorded.

Testing and common issues

• Portal opens but logo/verification missing: the Captivo domains may be missing from the allowed addresses (check the alias).
• Verification fails: confirm the RADIUS server is selected in the zone and the shared secret matches on both sides.
• Rate limit not applied: OPNsense does not read WISPr; check your Traffic Shaper rule.

Ready to go?

Create a free Captivo account, design your portal in minutes and add branded, compliant guest WiFi to your OPNsense Captive Portal.