UniFi Captive Portals Explained: Hotspot Portal vs. External Portal Server

UniFi is one of the most popular choices for small and mid-sized business Wi-Fi, and “how do I add a captive portal to UniFi?” is a common next question. UniFi gives you two routes: the built-in Hotspot Portal, and an External Portal Server that hands the login page to someone else’s software. This guide explains how each works, and why we think the second needs more care than most guides admit.

For the basics, see What Is a Captive Portal?

Option 1: UniFi’s built-in Hotspot Portal

UniFi Network includes a captive portal, called the Hotspot Portal or Hotspot Manager depending on the version. You enable it on a guest network in the UniFi Network application and choose how guests get in, typically:

• simply accepting your terms,
• a shared password,
• vouchers you print or hand out,
• or, depending on version and region, payment or RADIUS-based authentication.

You can customise the page with your logo, colours and text.

Where it falls short: the built-in portal is designed to control access. It is not built to engage guests. It doesn’t give you a proper way to collect guest email addresses with marketing consent, sync them to a CRM or newsletter tool, or add tracking for remarketing. For many businesses those are the whole point of a captive portal (see Captive Portals: A Business Strategy for Enhanced User Data Collection and Marketing).

Option 2: External Portal Server

For anything more, UniFi lets you point the guest network at an External Portal Server: a web server you or a third party run, which shows the login page instead of UniFi’s own.

Ubiquiti does not publish detailed documentation for this flow. What follows is how it works in practice, as reverse-engineered by open-source projects:

1. A guest joins the Wi-Fi. The UniFi gateway places them in a walled garden and redirects their browser to your external portal. The redirect URL carries parameters that identify the session: the guest’s MAC address, the access point’s MAC, the SSID, a timestamp and the URL they originally requested.

2. The guest completes your page, for example by entering an email or accepting terms.

3. Your portal authorises the guest by calling the UniFi controller’s API, along the lines of:

   POST /api/s/<site>/cmd/stamgr
   Content-Type: application/json
   
   {"cmd": "authorize-guest", "mac": "<guest MAC>", "minutes": 480}
   

4. The controller opens the gate for that MAC address for the given number of minutes, and the portal sends the guest on to their original URL or a welcome page.

Step 3 is the catch.

The security trade-off with UniFi external portals

To call authorize-guest, the portal must:

• reach the UniFi console directly. The controller API is not available through Ubiquiti’s cloud dashboard, so a hosted portal service needs the console exposed to the internet; and
• log in with an account that has admin-level rights. UniFi’s role model has no narrow “may only approve guests” permission that works for this. An undocumented hotspotoperator role looked promising, but in practice it didn’t work.

So most hosted “UniFi captive portal” services ask you to expose your console and give them admin credentials. That gives a third party full control of your network: firewall rules, DNS, VLANs, every device. If they are breached, so are you.

This is why we paused our own UniFi captive portal service: we were not willing to ask customers for that level of access. Viktor’s technical write-up has the full background.

A safer way to run an external portal on UniFi

If you need more than the Hotspot Portal offers, the lowest-risk set-up today is:

1. Run the portal on your own local network, on a small server or container behind the UniFi gateway, so the console never has to be reachable from the internet.
2. Create a dedicated local admin account for the portal. Don’t reuse your own, and use a long unique password.
3. Restrict who can reach the console with firewall rules, so only the portal server can talk to it.
4. Use a maintained library rather than writing the API calls from scratch. Good starting points:
   • unifi-hotspot, a Node.js captive portal that can send sign-ups to Google Sheets;
   • UniFi API Client, a PHP client maintained by Art of WiFi;
   • aiounifi, the Python library used by Home Assistant.
5. Serve the portal over HTTPS and keep the data you collect to a minimum (see Is a Captive Portal Login Safe?).

UniFi captive portal FAQ

Is UniFi’s built-in captive portal free?

Yes. The Hotspot Portal is part of UniFi Network at no extra cost. You only pay for an external portal service if you choose one.

Why isn’t my UniFi captive portal showing?

Check that the portal is enabled on the right (guest) network, and that the guest’s device isn’t using a VPN or encrypted DNS that bypasses the redirect. Our troubleshooting guide covers the client side.

How do I turn off the captive portal on UniFi?

Disable the Hotspot Portal (or the external portal setting) on the guest network in the UniFi Network application. Guests will then join with just the Wi-Fi password, if one is set.

Can I collect guest emails with UniFi?

Not well with the built-in portal alone. You need an external portal, with the security trade-offs above, to collect emails with consent and pass them to your marketing tools.