Back to Blog
Homelab 4 min read

Building a Voucher-Auth Guest Network on UniFi — Isolation, Speed Limits, and Captive Portal

A completely isolated guest VLAN with captive portal + voucher authentication, per-device speed limits, and no fallback DNS — designed to be welcoming but not a liability.

A guest network needs to be welcoming without being a security liability. The approach: isolate guest traffic completely on its own VLAN, require authentication via one-time vouchers before internet access, enforce speed limits per voucher, and block any inter-VLAN access.

Network and VLAN Configuration#

SSID: its own guest SSID. VLAN: dedicated and isolated. Network: untrusted zone. DNS: only the internal Pi resolver, no fallback. DHCP lease time: 86400 seconds (24 hours). This lease duration is long enough that a guest doesn't lose their session and have to re-enter a voucher during a day visit, but short enough that it's not excessive.

The network is completely air-gapped from all internal subnets. MGMT, Admin, IPTV, Users, Skynet, and VPN traffic cannot reach the Guest VLAN, and Guest traffic cannot initiate connections to any internal VLAN. The only direction allowed is Guest outbound to the internet.

Captive Portal with Voucher Authentication#

UniFi's built-in captive portal intercepts HTTP on port 80 from the Guest VLAN and presents an authentication page before any other traffic flows. The voucher authentication method requires guests to enter a code. The codes are single-use with 30-day validity. One voucher per guest, one guest per voucher.

When a guest connects to the guest SSID and opens their browser, they're redirected to the portal page where they enter the voucher code. The code is validated against the UniFi system. If valid, the guest is authenticated and receives a 24-hour internet session. If invalid or already used, the page rejects the entry and prompts again.

Speed Limits: Per-Voucher Enforcement#

Each voucher has speed limit settings: 25 Mbps download, 5 Mbps upload. These limits are enforced by the UniFi gateway's traffic shaping engine on a per-device basis.

The WAN connection itself (ISP link) has Smart Queues configured: 950 Mbps down / 47 Mbps up, matching the ISP plan. Guest traffic is shaped within the overall WAN queue and is capped per-device. If two guests are connected simultaneously, each gets their 25 Mbps cap independently. They don't compete for a shared pool — they're individually rate-limited.

This prevents a guest from saturating the WAN link. Even if a guest leaves a large file download running all day, it's capped at 25 Mbps.

Captive Portal HTTPS Gotcha#

UniFi's captive portal intercepts HTTP traffic. It does not intercept HTTPS. If a guest connects and immediately tries to visit an HTTPS site (which is most sites today), that traffic is not intercepted by the portal. The TLS handshake fails because the portal can't intercept encrypted traffic. The guest gets a connection timeout or certificate error.

This is normal behavior, not a bug. The guest needs to visit an unencrypted HTTP site first (or let the browser's auto-redirect kick in and force-upgrade to HTTPS for a site that supports it). Once the HTTP request is made, the portal can intercept it, authenticate the voucher, and then subsequent HTTPS traffic flows normally.

Firewall Posture: Complete Isolation#

The Guest zone has no access to Internal, Trusted, Untrusted, or VPN zones. All inter-VLAN routing is disabled. The only allowed traffic is Guest outbound to WAN (External). No inbound from other VLANs. No lateral access.

This isolation means a guest cannot enumerate or access devices on the internal network — even if they were to discover internal IPs somehow, firewall policy would block them cold.

DNS Configuration: Single Resolver, No Fallback#

The Guest VLAN's DHCP scope serves only the internal Pi resolver as DNS. No secondary DNS server. No fallback to Cloudflare or Quad9. If the Pi is down, guests have no DNS.

This is intentional. It simplifies the network and makes the Pi's availability more observable — if guests suddenly lose connectivity, it's a sign that the Pi is having issues, which should trigger an alert.