Setting Up an External Captive Portal on UniFi: The Complete Guide

Why External Beats Built-In

UniFi ships with a built-in hotspot portal, and for a lot of venues it is the first thing they try. It works, in the sense that a page appears and guests get online. What it does not do is capture marketing-grade data: there is no proper consent flow, no branded design system, no connection to a guest database, and no automation running behind it. That is why every serious guest WiFi marketing deployment on UniFi uses the external portal server mode instead, where the controller hands the guest to a page you control and your platform tells the controller when to let them through.

This guide walks the entire flow on Ubiquiti UniFi hardware: what to configure, how the handshake actually works underneath, and the specific mistakes that account for most failed setups. If you are on TP-Link hardware instead, the equivalent walkthrough is our Omada integration reference.

What You Need Before You Start

• One or more UniFi access points, adopted and online in your UniFi Network application
• Access to the Network application itself: self-hosted controller, a Cloud Key, or a UniFi OS console such as a UDM
• A local admin account on the controller for API use. Do not use your Ubiquiti cloud SSO account for this: API authentication needs a local username and password, and accounts with two-factor enabled will not work for automated logins
• A VoqadoWiFi account. The Starter plan is free forever for one location and 25 logins a month, which is enough to validate the whole chain before you commit to anything

Step 1: Create the Guest Network

In the UniFi Network application, create a new WiFi network for guests. The exact menu location shifts between Network application versions, but the essentials do not:

• Security: Open, or WPA2 with a simple shared passphrase if you want a light barrier. The portal handles the real gate
• Guest policy enabled: this is what activates client isolation and the hotspot redirect machinery
• A dedicated VLAN if your switching supports it. Guests should never sit on the same segment as your POS or office machines. We cover the full design in the guest VLAN segmentation guide

Step 2: Enable the Hotspot Portal in External Mode

In the hotspot or guest control settings, enable the portal for your guest network and select External Portal Server. You will be asked for the address of the external server: this is the hostname of your VoqadoWiFi portal, which the dashboard shows you when you add a UniFi location.

Two settings in this area matter more than they look:

Pre-authorization access, sometimes labelled the allowed subnets or walled garden list. Before a guest is authorized, the controller blocks everything except the portal server. If your portal loads assets, fonts, or scripts from any additional hostname, those must be listed here too. VoqadoWiFi portals are deliberately self-contained on one origin, which keeps this list short, but if you ever see a portal that renders as unstyled text, an incomplete walled garden is the first suspect.

Authorization duration. This is how long a guest stays authorized before they see the portal again. For cafes and restaurants, 8 to 24 hours is sensible. Setting it to 30 minutes to squeeze out more portal impressions mostly generates irritation, not signups.

Step 3: Understand the Redirect Flow

Knowing what happens under the hood turns troubleshooting from guesswork into a checklist. The sequence:

1. The guest joins the SSID and gets a DHCP lease on the guest network.
2. The device fires its captive portal detection probe. UniFi intercepts it and answers with a redirect to the guest entry path on your portal server. The path looks like /guest/s/default/ where default is your site name, and the redirect carries query parameters: the client MAC address, the AP MAC address, the SSID, a timestamp, and the URL the device originally asked for.
3. The mini-browser opens and loads your portal. The guest completes the form and consents, or taps through without opting in if you allow that.
4. VoqadoWiFi calls your controller API and issues an authorize-guest command for that client MAC, with a session length.
5. The controller tells the AP to release the client. The detection probe now succeeds, the mini-browser reports success, and the guest is online.

The whole handshake takes 2 to 4 seconds when everything is configured correctly. The behaviour of that mini-browser has its own quirks, which we unpack in how the captive portal mini-browser works.

Step 4: Connect VoqadoWiFi to the Controller

In the VoqadoWiFi dashboard, add a location and select UniFi as the hardware type. You will need:

• Controller URL, including the port. Classic self-hosted controllers and Cloud Keys answer on port 8443. UniFi OS consoles such as the UDM Pro answer on 443 and prefix the network API with /proxy/network, which is a meaningful difference: the full walkthrough for those devices is the UDM Pro guest portal guide
• Site name. For most single-venue setups this is default. If you renamed the site, use the short internal name from the URL bar, not the display name
• The local admin credentials you created earlier

The controller must be reachable from the internet for the authorize call to arrive. If your controller sits behind NAT with no inbound access, do not rush to forward ports: a Cloudflare Tunnel does the same job without exposing anything.

Step 5: Test Like a Guest, Not Like an Admin

Run the full loop on a phone with WiFi assist disabled and mobile data off, so you see exactly what a guest sees:

1. Join the SSID. The portal should appear within 2 to 3 seconds.
2. Complete the form. You should land on the success state and have working internet immediately.
3. Check the VoqadoWiFi dashboard: the session and the contact should be there within seconds.
4. Forget the network, rejoin, and confirm the authorization window behaves the way you set it.

Test on at least one iPhone and one Android device. They implement portal detection differently and one passing does not guarantee the other.

The Pitfalls That Cause Most Support Tickets

The authorize call never reaches the controller. Symptom: the form submits, then the guest sits on a spinner and never gets online. Cause: the controller is not reachable from outside, the port is wrong, or a firewall rule is silently dropping the request. Verify reachability from an external network before blaming anything else.

Cloud SSO credentials used for the API. The login endpoint wants a local account. SSO accounts, and any account with MFA, will fail in ways that look intermittent.

Walled garden too broad. If you allow wide destination ranges pre-authorization, some devices decide they already have internet, skip the portal, and never authenticate. Keep the pre-auth list to exactly what the portal needs.

Self-signed certificate surprises. The controller presents a self-signed certificate by default. VoqadoWiFi handles this on the API side, but if you put your own reverse proxy in front of the controller, make sure it passes the API paths through untouched.

Client isolation blocking a locally hosted resource. If anything in your flow lives on the LAN, guest isolation will block it. Everything the guest touches should be on the internet side.

MAC randomization. Modern phones present a per-network private address. It stays stable for a given SSID on almost all devices, so returning guests are still recognised, but a guest who toggles the private address setting will look brand new. This is normal, not a fault.

What Good Looks Like

A healthy UniFi external portal deployment shows portal load times under 2 seconds, an authorize round trip under a second, and an opt-in rate somewhere between 45 and 65 percent if the portal design is doing its job. From there the marketing layer takes over, and the hardware disappears into the background, which is exactly where it belongs.

Set aside an hour for the first venue. Most of that hour is testing, not configuring. Start free with the Starter plan, or book a demo and we will walk your specific controller version together.