View podcast transcript
Captive Portal for Ubiquiti UniFi — A Purple Technical Briefing
[INTRODUCTION & CONTEXT — approximately 1 minute]
Welcome to the Purple Technical Briefing series. I'm your host, and today we're getting into the specifics of deploying an external captive portal on Ubiquiti UniFi infrastructure — one of the most widely deployed network platforms in hospitality, retail, and enterprise environments globally.
If you're an IT manager, network architect, or systems integrator working with UniFi Cloud Gateways, Dream Machines, or the UniFi Network Application, this episode is for you. We're going to walk through exactly how the external portal mechanism works under the bonnet, how to configure it correctly, where the common pitfalls are, and why overlaying Purple on top of a UniFi deployment is the right architectural decision for venues that need more than a basic splash page.
Let's get into it.
[TECHNICAL DEEP-DIVE — approximately 5 minutes]
First, let's understand what's actually happening when a guest connects to a UniFi SSID that has a captive portal enabled.
When a guest device associates with your guest SSID, the UniFi Access Point assigns it an IP address via DHCP as normal. But the device is immediately placed in what UniFi calls a "pending" state. In this state, the AP's built-in DNSmasq process intercepts every DNS query the device makes, regardless of what DNS server the device thinks it's using. The AP redirects all DNS traffic to itself.
Simultaneously, the AP runs a lightweight HTTP redirector on port 80. The moment the guest's browser makes any HTTP request — and this is the key word, HTTP, not HTTPS — the redirector fires back a 302 redirect, sending the browser to the captive portal splash page. This is the mechanism that triggers the "Sign in to WiFi" notification on iOS and Android devices.
Now, this is where the built-in portal versus external portal distinction becomes critical. With the built-in UniFi Hotspot Portal, the splash page is served directly by the UniFi Network Application. It's functional, it's quick to set up, but it's severely limited. You get basic password authentication, vouchers, and Stripe payments. There's no email capture, no social login, no GDPR consent management, no CRM integration, and no meaningful analytics beyond session counts.
When you configure an External Portal Server — which is the setting we're focused on today — you're telling the UniFi controller to redirect guests to a completely separate web application. In our case, that's Purple. The URL you enter in the External Portal Server field becomes the destination for all those 302 redirects.
Here's the important technical detail about that redirect URL. When UniFi redirects a guest to your external portal, it appends several query parameters to the URL. These include: the AP MAC address, the client device MAC address, a Unix timestamp, the original URL the client was trying to reach, and the SSID name. Your external portal — Purple in this context — captures those parameters, uses them to identify the connecting device, presents the appropriate splash page, handles authentication, and then makes an API call back to the UniFi Network Application to authorise that MAC address.
That API call is the crucial handshake. As of UniFi Network Application 9.1 and later, there's an official REST API with proper key-based authentication. The authorisation endpoint is a POST request to version one of the sites API, targeting the specific client ID, with a JSON body that can specify time limits in minutes, data usage limits in megabytes, and rate limits in kilobits per second. Once the controller receives that authorisation, it pushes the instruction to the AP, and the guest moves from pending to authorised. Internet access is granted.
Now let's talk about the Walled Garden, which UniFi calls Pre-Authorization Access. This is the whitelist of domains and IP addresses that guests can reach before they've authenticated. It's essential, and it's one of the most common sources of misconfiguration.
At a minimum, your walled garden needs to include the fully qualified domain name of your Purple portal, and the IP addresses or CIDR ranges that Purple's infrastructure resolves to. If you're using social login — Facebook, Google, Microsoft — you need to add the OAuth endpoint domains for those providers as well. Google's login endpoints span multiple IP ranges and several domains including accounts.google.com and oauth2.googleapis.com. Facebook's login infrastructure similarly requires several entries. Purple's documentation provides a maintained list of the exact entries required, and this list is kept current as those providers update their infrastructure.
There's a critical quirk specific to UniFi that catches a lot of deployments out. The HTTP redirector on the AP only intercepts plain HTTP traffic on port 80. Modern devices — iOS, Android, Windows, macOS — all perform HTTPS-based captive portal detection. Apple devices hit captive.apple.com over HTTPS. Android devices hit connectivitycheck.gstatic.com. If those HTTPS requests don't get a specific response, the device may decide there's no captive portal and simply fail to show the sign-in prompt.
The solution is to ensure your walled garden includes the captive portal detection domains for the major operating systems, and that your Purple portal is accessible over HTTPS with a valid, trusted SSL certificate. Self-signed certificates will cause browser security warnings that block the portal from loading. This is non-negotiable for production deployments.
The other UniFi-specific consideration is controller accessibility. The UniFi Network Application — whether it's running on a Cloud Gateway, a Cloud Key, or a self-hosted server — must be reachable from Purple's infrastructure for the API authorisation calls to succeed. If your controller is on a private network behind NAT, you'll need to ensure the relevant API ports are accessible. For self-hosted controllers, that's typically port 8443 for the legacy API, or the standard HTTPS port 443 for the newer API introduced in version 9.1. Purple's support documentation specifies the exact IP ranges that need inbound access to your controller.
For RADIUS-based authentication — which is relevant when you're deploying Purple alongside WPA2-Enterprise or WPA3-Enterprise SSIDs rather than the open guest SSID model — UniFi's built-in RADIUS server supports standard 802.1X EAP methods. You configure the RADIUS profile under Settings, Networks, RADIUS Servers, and then reference that profile in your SSID configuration. UniFi also supports RADIUS over TLS, known as RADSEC, from version 8.4 onwards, which encrypts the RADIUS traffic between the AP and the authentication server. For multi-site deployments where RADIUS traffic traverses the public internet, RADSEC is strongly recommended.
[IMPLEMENTATION RECOMMENDATIONS & PITFALLS — approximately 2 minutes]
Let me give you the practical implementation checklist that I'd walk through with any client deploying Purple on UniFi.
First, network segmentation. Your guest SSID must be on a dedicated VLAN, isolated from your corporate and IoT networks. UniFi makes this straightforward — create a dedicated network in Settings, Networks, assign it a VLAN ID, and associate your guest SSID with that network. Enable client isolation on the guest network to prevent guest-to-guest traffic.
Second, the controller must have a valid FQDN and a trusted SSL certificate. Don't rely on the IP address. Use a proper domain name, get a Let's Encrypt or commercial certificate on it, and configure UniFi to use that certificate. This resolves the majority of HTTPS redirect issues.
Third, build your walled garden carefully and test it. The minimum entries are: your Purple portal domain and its IP ranges, the captive portal detection domains for iOS, Android, and Windows, and any OAuth provider domains you're using. Test with a device that has never connected to the network before — cached DNS and network state can mask walled garden gaps during testing.
Fourth, for the API integration, use a dedicated local admin account in the UniFi Network Application with the minimum required permissions. Don't use your primary admin credentials. If you're on Network Application 9.1 or later, use the new API key mechanism under Control Plane, Integrations — it's more secure and doesn't require credential-based authentication.
Fifth, consider session duration carefully. UniFi's default guest session expiry can be as short as eight hours. For hospitality deployments where guests may be staying multiple nights, configure appropriate session durations in the Purple portal settings, and ensure those durations are passed correctly in the API authorisation call.
The most common pitfall I see is deploying on a self-hosted controller that isn't publicly accessible. If Purple can't reach your controller to authorise guests, the portal will load but authentication will silently fail. Always verify API connectivity from Purple's infrastructure before going live.
[RAPID-FIRE Q&A — approximately 1 minute]
Does this work on UniFi Dream Machine Pro? Yes. All UniFi OS consoles — UDM, UDM Pro, UDM SE, UCG Ultra, UCG-Max — support the External Portal Server configuration. The Network Application runs on-device.
Can I use Purple on multiple UniFi sites from a single Purple account? Yes. Purple's multi-site architecture is designed for exactly this. Each venue is configured as a separate site in Purple, mapped to the corresponding UniFi site.
Do I need to open firewall ports on the UniFi gateway? You need to ensure that guest VLAN traffic can reach the Purple portal domain on port 443. The controller API port also needs to be reachable from Purple's servers. Purple's documentation provides the specific IP ranges.
What about WPA3? UniFi supports WPA3 Personal and WPA3 Enterprise. The captive portal mechanism works with WPA3 Personal on guest networks. WPA3 Enterprise uses 802.1X and RADIUS, which is a different authentication flow.
[SUMMARY & NEXT STEPS — approximately 1 minute]
To summarise: deploying Purple as an external captive portal on UniFi is a well-supported, architecturally sound integration. The key steps are: configure your guest SSID with the External Portal Server option pointing to your Purple portal URL, build a comprehensive walled garden that covers Purple's infrastructure and any OAuth providers you're using, ensure your UniFi controller has a valid SSL certificate and is accessible from Purple's API servers, and configure appropriate session durations for your venue type.
The business case is straightforward. The built-in UniFi portal gives you a splash page. Purple gives you a compliance-ready, analytics-driven guest experience platform that integrates with your CRM, captures first-party data under GDPR consent, and provides the footfall and dwell-time analytics that venue operators and marketing teams actually need.
If you're an MSP or systems integrator deploying UniFi at scale, Purple's multi-site management and white-label capabilities make it the right overlay for your clients.
For detailed configuration documentation, walled garden IP lists, and API integration guides, visit purple.ai. Thank you for listening.
