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

UniFi stands as a top selection for small and mid-sized business Wi-Fi, often leading people to ask “how do I add a captive portal to UniFi?”. There are two paths provided by UniFi: using the built-in Hotspot Portal or setting up an External Portal Server that delivers the login page via third-party software. Here we outline how each functions, noting why the latter requires more attention than typical guides suggest.

For the basics, see What Is a Captive Portal?

Option 1: UniFi’s built-in Hotspot Portal

The UniFi Network comes with a captive portal, referred to as the Hotspot Portal or Hotspot Manager based on the software version. Activation happens within a guest Wi-Fi network inside the UniFi Network app, where you select how visitors enter, usually:

• agreeing to your conditions directly,
• using one shared password,
• redeeming printed vouchers or those distributed manually,
• or, contingent on version and location, payment methods or RADIUS-based verification.

You may tailor the display using your own logo, colours, and written content.

Where it falls short: this integrated gateway is built to manage access. It lacks tools to connect with visitors. There is no effective method to gather visitor email addresses with consent, upload them to a CRM or newsletter platform, or implement tracking for future outreach. For many companies, these features represent the core value of a captive portal (see Captive Portals: A Business Strategy for Enhanced User Data Collection and Marketing).

Option 2: External Portal Server

If you require additional features, UniFi allows directing the guest Wi-Fi network toward an External Portal Server: a web host operated by you or another entity that displays the login page rather than UniFi’s default interface.

Ubiquiti has not released comprehensive docs for this process. The steps below describe practical operation based on analysis from open-source initiatives:

1. A visitor connects to the Wi-Fi. The UniFi gateway isolates them in a walled garden and sends their browser to your external portal. The redirect link includes parameters identifying the session: the user’s MAC address, the access point’s MAC, the SSID, a time stamp, and the URL they originally requested.

2. The visitor finishes your form, such as typing in an email or agreeing to conditions.

3. Your server validates the visitor by contacting the UniFi controller’s API, similar to:

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

4. The controller unlocks access for that MAC address for the specified duration, then the portal directs the visitor back to their initial URL or a welcome screen.

The third step presents the issue.

The security trade-off with UniFi external portals

To invoke authorize-guest, the portal needs to:

• connect directly to the UniFi console. The controller API cannot be accessed via Ubiquiti’s cloud interface, meaning a hosted portal requires the console to face the internet; and
• sign in using credentials with admin-level rights. UniFi’s permission structure lacks a specific “may only approve guests” access for this task. An undocumented hotspotoperator role seemed viable, but in practice it didn’t work.

Consequently, many hosted “UniFi captive portal” providers request you to expose your console and give them admin credentials. This grants a third party complete authority over your network: firewall settings, DNS, VLANs, every device. If they suffer a breach, you are compromised as well.

This explains why we paused our own UniFi captive portal service: we refused to request such extensive access from clients. Viktor’s technical write-up provides the complete context.

A safer way to run an external portal on UniFi

If you require more than the Hotspot Portal provides, the safest configuration currently available is:

1. Operate the captive portal within your private local network, using a modest server or container positioned behind the UniFi gateway, ensuring the console remains inaccessible from the internet.
2. Establish a distinct local administrator account specifically for the captive portal. Avoid using your existing credentials, and implement a lengthy, unique password instead.
3. Limit access to the console via firewall configurations, allowing communication solely from the captive portal server itself.
4. Instead of coding API requests manually, select an actively supported library. Recommended options include:
   • unifi-hotspot, which functions as a Node.js captive portal capable of transmitting registrations to Google Sheets;
   • UniFi API Client, a PHP client kept up-to-date by Art of WiFi;
   • aiounifi, the Python library used by Home Assistant.
5. Host the captive portal using HTTPS, and limit the amount of information gathered (refer to Is a Captive Portal Login Safe?).

UniFi captive portal FAQ

Is UniFi’s built-in captive portal free?

Correct. The Hotspot Portal comes included with UniFi Network without additional fees. Fees apply only if you opt for an external portal service.

Why isn’t my UniFi captive portal showing?

Verify the captive portal is active on the correct (guest) network, and ensure the visitor’s device does not use a VPN or encrypted DNS to skip the redirect mechanism. Our troubleshooting guide addresses the client-side issues.

How do I turn off the captive portal on UniFi?

Deactivate the Hotspot Portal (or the external portal configuration) within the UniFi Network application for the guest network. Users can subsequently connect using only the Wi-Fi passphrase, provided it has been configured.

Can I collect guest emails with UniFi?

The integrated solution handles this poorly on its own. To gather email addresses with permission and forward them to marketing systems, you require an external portal, accepting the security compromises mentioned previously.