Ubiquiti UniFi

UniFi captive portal setup, start to finish

Enable the hotspot portal, point it at an external portal server, and allow the domain through pre-authorisation. That is the whole change. The part nobody warns you about is which site name goes in the URL.

Generate my UniFi settings Is my controller supported?

How do I set up a captive portal on UniFi?

In the UniFi Network application open Settings, WiFi, select your guest SSID, and enable the hotspot portal with an external portal server. Point it at https://www.voqadowifi.com/guest/s/<site> using your internal site name, then add the portal domain to the pre-authorisation access list.

The six steps

Find your internal site name
Open the UniFi Network application with the right site selected and read the browser address bar. The short identifier after /manage/ is the site name. It is usually nothing like the display name you typed.
Open the hotspot portal settings for your guest SSID
Go to Settings, WiFi, and open the guest SSID. Enable the hotspot portal, then choose an external portal server rather than the built in one.
Enter the external portal server address
Use https://www.voqadowifi.com/guest/s/your-site-name, substituting the internal site name from step one. UniFi appends the client MAC, access point MAC and its own parameters on the redirect.
Add the pre-authorisation entries
Add www.voqadowifi.com and voqadowifi.com to the pre-authorisation access list so an unauthorised device can reach the portal domain before it is allowed online.
Connect the controller from the VoqadoWiFi dashboard
Enter the controller address and a controller login in the dashboard. A UniFi OS appliance takes an address with no port; a self hosted Network Server normally needs port 8443.
Test on a phone that has never joined the network
Join the guest SSID on a device with no remembered connection, submit the form, and confirm the device reaches the internet.

The site name trap

When you create a site in UniFi you give it a friendly name, something like “Harbour Bar Main”. UniFi quietly assigns it a short internal identifier at the same time, and every API path uses that identifier, not your friendly name.

Put the friendly name in the portal URL and everything looks right. The portal loads, your logo appears, the form submits. Then nothing happens, because the authorisation call is aimed at a site that does not exist.

Where to find the real one. Open the Network application with that site selected and look at the address bar. The segment immediately after /manage/ is the internal site name. On a single site console it is often literally default.

Which controller you have, and what changes

Three UniFi deployments, one setting
Deployment	Typical address	What is different
UDM, UDM Pro, UDR, Cloud Key	https://your-address, no port	Runs UniFi OS. The Network application sits behind a proxy path, which the integration handles automatically.
Self hosted Network Server	https://your-server:8443	The older login path. Include the port, or detection has to guess.
Official UniFi cloud console	unifi.ui.com	Ubiquiti hosted. Same portal setting, reached through their console.

A note on reaching the controller

Authorising a guest device is a call into your controller, so the controller has to be reachable. A Cloudflare Tunnel is the recommended route: it is free, it needs no port forwarding, and it does not put a controller login on the open internet. It also strips some response headers, which breaks naive UniFi integrations. This one reads the CSRF token from the session cookie when the header is missing, so a tunnelled UDM Pro works.

What UniFi already does for free

Built in UniFi hotspot versus an external Social WiFi portal
Capability	UniFi on its own	With an external portal
Terms and conditions page	Yes	Yes
Vouchers and simple password	Yes	Yes, plus email sign in
Payment for access	Yes, via its own integrations	Not offered
Keep the guest email address	No	Yes, with consent recorded
Automatic review request after the visit	No	Yes
Guest CRM and repeat visit history	No	Yes
Export the list	No	Yes, CSV at any time

Worth saying plainly: if you want to charge for WiFi, UniFi’s own hotspot does that and this platform does not. If you want to keep who came in, it is the other way round.

Before you start

The guest SSID should be open. A portal behind a WPA password is a door behind a door.
Leave guest isolation on. Guests should not reach each other or your point of sale.
Create a dedicated controller account for the integration instead of sharing your own administrator login.
Enabling the hotspot portal drops devices currently on that SSID while they reconnect. Pick a quiet hour.

UniFi questions

What is a UniFi external portal server?

It is the setting that tells UniFi to stop showing its own guest login page and redirect unauthenticated devices to an address you control instead. The external service then calls back into the controller to authorise each device once the guest has signed in.

Does UniFi already have a captive portal?

Yes, and for some venues it is enough. The built in hotspot can show terms, take a simple password or accept vouchers. What it does not do is keep the guest email address in a form you can market to, or send anything after the visit.

Why is my portal loading but nobody gets online?

The most common cause is the wrong site name in the URL. The display name you typed when creating the site is not the internal identifier UniFi uses. A portal built on the display name loads fine and then fails to authorise anyone, because the authorisation call targets a site that does not exist.

Does this work on a UDM Pro behind Cloudflare Tunnel?

Yes, and it is a supported path. UniFi OS carries its CSRF token in both a response header and a cookie, and a reverse proxy can strip the header. The integration reads the token from either source, so a tunnelled UDM Pro authorises guests correctly rather than returning 403 on every attempt.

Which UniFi controllers are supported?

UniFi OS appliances such as the UDM, UDM Pro, UDR and Cloud Key, the self hosted UniFi Network Server on port 8443, and the official UniFi cloud console. The integration detects which one it is talking to rather than asking you.

Do I need a public IP or port forwarding?

The controller has to be reachable from the internet for the authorisation call to land. A Cloudflare Tunnel is the recommended way to do that without exposing the controller directly, and it is free. Opening a port to a controller is the alternative and it is a worse idea.

Keep reading

Generate the exact settings for your controllerThree questions, then a copyable pack.UniFi integration details and supported controllersWhat the integration does, rather than how to switch it on.The same walkthrough for TP-Link Omada Omada or UniFi, which to buy What Social WiFi isWhy the email address is the point, not the login.

Ubiquiti and UniFi are trademarks of Ubiquiti Inc. VoqadoWiFi is not affiliated with, endorsed by, or sponsored by Ubiquiti. Menu labels move between Network application releases; the setting stays under the guest SSID’s hotspot portal options.