Skip to main content
English (UK)

Captive Portal for Ubiquiti UniFi

This authoritative technical guide details the configuration of an external captive portal (Purple) on the Ubiquiti UniFi Network Application. It covers the underlying network mechanics, step-by-step guest network deployment, walled garden whitelisting, RADIUS authentication, and troubleshooting strategies for senior IT professionals and network administrators.

📖 10 min read📝 2,475 words🔧 2 worked examples❓ 3 practice questions📚 8 key definitions

Listen to this guide

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 hood, 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.

📚 Part of our core series: Multi-Tenant WiFi →

header_image.png

Executive Summary

As enterprise physical venues — ranging from large-scale retail chains [1] and multi-site hospitality groups [2] to major transport hubs [3] and educational institutions [4] — seek to maximize the value of their wireless infrastructure, the limitations of built-in hotspot controllers become a significant operational bottleneck. The Ubiquiti UniFi ecosystem provides highly reliable, cost-effective, and scalable hardware. However, its native guest portal lacks the advanced data capture, multi-site analytics, CRM integration, global privacy compliance (GDPR, CCPA, PCI DSS), and monetization capabilities required by modern enterprise operations.

This technical reference guide provides a comprehensive architectural walkthrough for overlaying Purple's Enterprise WiFi Intelligence Platform [5] onto a Ubiquiti UniFi Network architecture. By utilizing UniFi's External Portal Server capability, network architects and systems integrators can bypass local controller limitations. This integration routes guest authentication through Purple's secure, cloud-hosted identity and analytics engine, transforming a basic utility into an enterprise-grade marketing and operational asset.

Technical Deep-Dive

To deploy a secure and stable external captive portal, network engineers must understand the low-level communication and state transitions that occur when an unauthenticated client connects to the wireless network.

The Guest Connection and Redirection Lifecycle

The UniFi captive portal workflow operates on a strict state-based model. When a client associates with a guest-enabled SSID, the following sequential process is initiated:

Phase Component Action / State Transition Technical Mechanism
1. Association Client & Access Point Client associates with the SSID; DHCP server assigns IP address, subnet mask, gateway, and DNS servers. Standard 802.11 association and DHCP lease.
2. Quarantine UniFi Access Point (AP) AP places the client MAC address in a Quarantined / Pending state (authorized: false). Layer 2/3 blocking rules applied locally on the AP's virtual interface.
3. DNS Interception AP Local Daemon AP runs a local DNSmasq process that intercepts all DNS queries from pending clients. AP redirects all port 53 (UDP/TCP) traffic to its local DNS resolver, regardless of client DNS settings.
4. HTTP Interception AP Redirector AP runs a lightweight HTTP redirector daemon on port 80. Any HTTP request made by the client is intercepted. The AP responds with an HTTP 302 Found redirect.
5. Redirection Client Browser Client's browser (or the OS Captive Portal Assistant) is redirected to the configured External Portal URL. The 302 redirect URL is appended with critical query parameters containing client and AP metadata.
6. Authentication External Portal (Purple) Client interacts with the Purple splash page, completing authentication (e.g., social login, email registration, SMS OTP). Secure HTTPS session hosted on Purple's cloud infrastructure.
7. API Handshake Purple Cloud & UniFi Controller Purple validates the credentials and issues a secure API call to the UniFi Network Application. REST API call (POST request) containing the client MAC address, site ID, and session parameters.
8. Authorization UniFi Controller & AP UniFi Controller updates the client state to authorized: true and pushes the updated ACL to the AP. AP removes Layer 2/3 blocks for the client MAC address, granting full routing to the internet gateway.

The Redirection Query Parameters

When the UniFi AP issues the HTTP 302 redirect, it appends a standardized set of query parameters to the External Portal URL. The external portal must capture these parameters to identify the client and perform the subsequent API authorization:

https://portal.purplehotspot.com/guest/s/default/?ap=94:2a:6f:d0:30:57&id=1c:71:25:63:e4:24&t=1742398732&url=http://connectivitycheck.gstatic.com%2F&ssid=purple-guest
  • ap: The MAC address of the specific UniFi Access Point to which the client is associated.
  • id: The MAC address of the client device requesting network access.
  • t: A Unix epoch timestamp representing the redirect initiation time, used for security verification.
  • url: The original URL the client attempted to access (often an OS captive portal detection endpoint).
  • ssid: The SSID name the client connected to, allowing the portal to present site-specific branding.

architecture_overview.png

The Walled Garden (Pre-Authorization Access Control)

Before a client is authorized, all traffic is blocked except for destinations explicitly defined in the Pre-Authorization Access list (commonly referred to as the Walled Garden). Because modern client devices run automated Captive Portal Assistants (CPAs) that test connectivity over HTTPS, and because external authentication often relies on third-party identity providers (IdPs), configuring a robust and accurate walled garden is critical.

If a required domain or IP range is omitted from the walled garden, the splash page will fail to load, social login buttons will freeze, or the client device will drop the WiFi connection entirely, assuming a broken network.

Implementation Guide

This section outlines the step-by-step configuration required to integrate Purple's External Captive Portal with the Ubiquiti UniFi Network Application (Controller).

Step 1: Network Segmentation and VLAN Configuration

To ensure enterprise-grade security and compliance (such as PCI DSS and GDPR), guest traffic must be completely isolated from corporate resources, POS systems, and IoT networks.

  1. Navigate to Settings > Networks in the UniFi Network Application.
  2. Click Create New Network.
  3. Configure the network settings as follows:
    • Name: Purple Guest Network
    • VLAN ID: 90 (or any dedicated guest VLAN tag)
    • Network Type: Guest (this automatically applies client isolation, preventing guest-to-guest communication).
    • Gateway IP/Subnet: Configure an appropriate subnet (e.g., 10.90.0.1/22 to support up to 1022 concurrent guest leases).
    • DHCP Range: Enable DHCP and define the range (e.g., 10.90.0.10 to 10.90.3.254).
    • DNS Server: Set to reliable public resolvers (e.g., Cloudflare 1.1.1.1 and Google 8.8.8.8) to ensure fast DNS resolution.

Step 2: Guest SSID Configuration

  1. Navigate to Settings > WiFi and click Create New WiFi Network.
  2. Configure the SSID parameters:
    • Name (SSID): Purple Guest WiFi
    • Security Protocol: Open (the captive portal will handle authentication).
    • Network: Select the Purple Guest Network (VLAN 90) created in Step 1.
    • Client Device Isolation: Ensure this is toggled ON.
  3. Scroll down to Hotspot Portal and check the box to Enable Captive Portal.

Step 3: Configuring the External Portal Server

Once the Hotspot Portal is enabled, you must redirect authentication to Purple's secure cloud servers.

  1. Navigate to Settings > Profiles > Guest Hotspot (or Settings > Guest Control in older controller versions).
  2. Under Authentication, select External Portal Server.
  3. Configure the following fields:
    • IP / FQDN: Enter the FQDN provided by Purple (e.g., portal.purplehotspot.com).
    • Use Secure Portal (HTTPS): Toggle ON (Mandatory for security and modern browser compatibility).
    • Redirect Using Hostname: Toggle ON and enter the FQDN portal.purplehotspot.com.
    • Port: 443 (standard HTTPS).
    • HTTPS Redirection: Toggle ON (this allows the AP to intercept initial HTTPS requests and redirect them, though it requires careful DNS management).

Step 4: Configuring Pre-Authorization Access (Walled Garden)

To allow unauthenticated guests to load the Purple splash page and authenticate via third-party IdPs, add the following domains and IP ranges to the Pre-Authorization Access list under Settings > Profiles > Guest Hotspot > Pre-Authorization Access:

[
  "portal.purplehotspot.com",
  "*.purple.ai",
  "*.purplehotspot.com",
  "accounts.google.com",
  "ssl.gstatic.com",
  "*.googleapis.com",
  "*.facebook.com",
  "*.facebook.net",
  "*.fbcdn.net",
  "*.apple.com",
  "captive.apple.com",
  "connectivitycheck.gstatic.com",
  "*.microsoft.com",
  "*.live.com"
]

Note: For deployments utilizing Stripe payment processing, add *.stripe.com and *.stripe.network to the pre-authorization list.

Step 5: Establishing the API Handshake

For Purple to authorize guests, its cloud servers must communicate with your UniFi Network Application.

For UniFi Network Application 9.1 and Later (Recommended REST API)

  1. In the UniFi controller, navigate to Settings > Control Plane > Integrations.
  2. Under the API Keys section, click Generate New API Key.
  3. Assign a name (e.g., Purple Integration Key) and set the permissions to Administrator.
  4. Copy the generated API Key.
  5. Log in to your Purple Portal, navigate to Venue Settings > Integration > Ubiquiti UniFi, and paste the API Key along with your UniFi Controller's public FQDN (e.g., unifi.yourdomain.com:443).

For Legacy Controllers (Credential-Based API)

  1. Navigate to Settings > System > Admins.
  2. Create a dedicated local administrator account (e.g., purple_api).
  3. Assign Administrator or Hotspot Operator privileges.
  4. Configure a strong, unique password.
  5. In the Purple Portal, enter these credentials under the UniFi Integration tab.

Best Practices

1. SSL Certificate Requirements

Never use a self-signed SSL certificate on a production UniFi Controller or External Portal Server. Modern web browsers and operating system Captive Portal Assistants (CPAs) enforce strict SSL/TLS validation. A self-signed certificate will trigger a highly visible security warning (e.g., "Your connection is not private"), leading to high abandonment rates and brand damage.

  • Deploy a valid, publicly trusted SSL certificate (e.g., Let's Encrypt or a commercial CA certificate) on the UniFi Controller's FQDN.
  • Ensure that the controller's FQDN resolves correctly from both the internal guest VLAN and the public internet.

2. DNS Configuration

Slow DNS resolution is the primary cause of sluggish captive portal redirection.

  • Do not point guest DNS to the UniFi Gateway's local IP unless the gateway has high-performance DNS forwarding configured.
  • Instead, configure the guest DHCP scope to distribute fast, resilient public DNS servers directly to clients (e.g., Primary: 1.1.1.1, Secondary: 8.8.8.8).

3. RADIUS Guest WiFi Configuration (Enterprise Alternative)

For venues requiring certificate-based or credential-based 802.1X security rather than an open SSID with a web portal, UniFi supports external Cloud RADIUS integration [6].

  • Configure a RADIUS Profile under Settings > Profiles > RADIUS.
  • Enter the Primary and Secondary RADIUS Server IPs and Shared Secrets provided by Purple.
  • Enable RADIUS Accounting and set the Interim Update Interval to 300 seconds to ensure real-time session tracking.
  • Under the SSID settings, set the Security Protocol to WPA2 Enterprise or WPA3 Enterprise [7] and select the RADIUS Profile.

comparison_chart.png

Troubleshooting & Risk Mitigation

When deploying external captive portals, network administrators frequently encounter several common failure modes. The table below details these issues, their root causes, and exact mitigation steps:

Symptom Root Cause Analysis Corrective Action & Mitigation
White Screen / Portal Fails to Load The client device cannot resolve or reach the FQDN of the external portal server. 1. Verify that portal.purplehotspot.com is in the Pre-Authorization Access list.
2. Ensure the guest client has received a valid IP and DNS server via DHCP.
3. Perform a DNS lookup on the client device to verify resolution of the portal FQDN.
"Connection Not Private" SSL Error The UniFi Controller is using a self-signed certificate, or the redirection FQDN does not match the SSL certificate common name. 1. Install a publicly trusted SSL certificate on the UniFi Controller.
2. Verify that Redirect Using Hostname is enabled and matches the FQDN on the certificate exactly.
3. Disable "Redirect HTTPS" in the UniFi guest control settings to prevent the AP from trying to intercept HTTPS traffic on port 443, which naturally triggers SSL warnings.
Authentication Succeeds, but Internet is Blocked The Purple cloud was able to authenticate the user, but the API call to authorize the client MAC address on the UniFi Controller failed. 1. Check firewall rules to ensure port 443 (or 8443 for legacy) is open inbound to the UniFi Controller from Purple's IP ranges.
2. Verify that the API Key or local admin credentials entered in the Purple Portal are valid and have Administrator permissions.
3. Check the UniFi Controller logs (server.log) for API authentication failures.
Social Login (e.g., Google) Buttons Fail to Work The IdP's authentication domains are blocked by the AP's access control list. 1. Add the complete wildcard domains for the specific IdP to the Pre-Authorization Access list (e.g., *.google.com, *.googleapis.com).
2. If using Facebook, ensure the Facebook SDK domains are fully whitelisted.
Frequent Disconnections / Re-authentication Prompts The UniFi Controller session timeout is shorter than the Purple session duration, or DHCP lease times are too short. 1. Align the UniFi Guest Hotspot Session Timeout setting with the Purple session policy (e.g., 24 hours).
2. Increase the DHCP lease time on the Guest VLAN to at least 12 or 24 hours to prevent IP address exhaustion and mid-session re-auth.

ROI & Business Impact

While deploying an external captive portal requires careful network engineering, the business outcomes and return on investment (ROI) far outweigh the initial implementation complexity.

Enterprise Data Capture and CRM Enrichment

The native UniFi guest portal is a "blind" utility; it grants internet access without capturing user identity. By overlaying Purple, venues can capture valuable first-party data (emails, phone numbers, social profiles) in a fully GDPR and CCPA-compliant manner. This data is automatically synchronized in real-time with CRM systems, marketing platforms (e.g., Salesforce, HubSpot, Mailchimp), and loyalty programs, enabling highly targeted marketing campaigns that drive repeat visits and customer lifetime value.

Multi-Site Management and White-Labeling

For Managed Service Providers (MSPs) and multi-site enterprise operators, managing guest WiFi across hundreds of venues via individual UniFi controllers is highly inefficient. Purple provides a single, centralized cloud dashboard to manage splash pages, compliance terms, and analytics across all venues globally, regardless of the underlying UniFi controller distribution.

Real-Time Analytics and Spatial Intelligence

Purple transforms the UniFi wireless network into a powerful sensor array. By analyzing probe requests and connection metadata, Purple delivers deep spatial intelligence, including:

  • Footfall Analytics: Total visitors, pass-by traffic, and conversion rates (pass-by to enter).
  • Dwell Time: Average duration of visits, segmented by customer type (new vs. returning).
  • Recency and Frequency: How often customers return and the elapsed time between visits.
  • Venue Heatmaps: Visual representation of visitor flow and density, enabling retail and venue operators to optimize layouts and staffing.

Monetization via Retail Media Networks

For large venues such as stadiums, shopping malls, and airports, the captive portal splash page represents highly valuable digital real estate. Purple enables venues to monetize this space by integrating with retail media networks, serving targeted programmatic advertising, sponsored login experiences, and localized promotions directly to guests at the moment of connection.

References

Key Definitions

Captive Portal

A web page that intercepts a guest's initial network connection and requires authentication, registration, or acceptance of terms before granting full internet access.

Encountered immediately upon connecting to an open guest SSID; managed by the AP redirector and external portal server.

External Portal Server

A third-party web application (such as Purple) that hosts the guest splash page and handles user authentication, bypassing the built-in controller's portal limitations.

Configured in UniFi Guest Hotspot settings to replace the native UniFi landing page.

Walled Garden (Pre-Authorization Access)

A whitelist of domains, subdomains, or IP addresses that unauthenticated clients can access before completing the captive portal login process.

Essential for loading the portal page itself, CSS/JS assets, and third-party OAuth login endpoints.

DNSmasq

A lightweight DNS forwarder and DHCP server run locally on UniFi Access Points to intercept and redirect guest DNS queries during the pre-authorization state.

Handles the initial DNS redirection that forces client devices to trigger their built-in captive portal assistants.

API Authorization Handshake

The process where the external portal server (Purple) makes a secure API call back to the UniFi controller to transition a client MAC address from 'quarantined' to 'authorized'.

Occurs immediately after the user successfully completes the login flow on the splash page.

Client Device Isolation

A security feature that prevents wireless clients on the same SSID or VLAN from communicating with each other, mitigating the risk of local network attacks.

Enabled in UniFi WiFi and Network settings to protect guest privacy and secure the venue's network.

RADSEC (RADIUS over TLS)

A protocol that secures RADIUS authentication and accounting traffic by wrapping it in a secure TLS tunnel, preventing eavesdropping and tampering over public networks.

Supported in UniFi Network 8.4+ for secure multi-site enterprise deployments using WPA2/WPA3 Enterprise.

CPA (Captive Portal Assistant)

A built-in operating system utility on iOS, Android, Windows, and macOS that automatically detects a captive portal by attempting to fetch a known HTTP/HTTPS endpoint.

Triggers the 'Sign in to WiFi' popup window on the user's device immediately after connection.

Worked Examples

A high-footfall shopping mall with 150 UniFi APs and a self-hosted UniFi Network Application on AWS needs to deploy Purple. The IT team wants to use Google and Facebook social login for guest authentication. However, during initial testing, guests clicking the social login buttons are met with a blank screen or a DNS resolution error.

The issue is caused by a restrictive walled garden (Pre-Authorization Access) that prevents the guest's device from resolving or reaching the authentication endpoints of Google and Facebook before they are authorized. To resolve this, the network administrator must log in to the UniFi Network Application, navigate to Settings > Profiles > Guest Hotspot, and expand the Pre-Authorization Access section. They must add the complete wildcard domains for Google and Facebook identity providers. For Google, this includes accounts.google.com, ssl.gstatic.com, and *.googleapis.com. For Facebook, it requires *.facebook.com, *.facebook.net, and *.fbcdn.net. Additionally, ensure that the guest network's DHCP scope is configured to distribute fast, public DNS servers (e.g., 1.1.1.1 and 8.8.8.8) directly to clients, rather than pointing them to the local UniFi gateway, which can become a bottleneck for pre-authorization DNS queries.

Examiner's Commentary: This is a classic 'walled garden gap' failure. Because social login flows rely on complex OAuth redirects across multiple subdomains, omitting even a single asset delivery domain (like Facebook's CDN `fbcdn.net`) will break the page rendering. Network architects should always use wildcards (`*.domain.com`) where supported by the controller, and verify DNS resolution from an unauthenticated client using standard tools like `nslookup` or `dig` against the whitelisted domains.

An MSP is deploying Purple across a chain of 50 boutique hotels. Each hotel has a local UniFi Cloud Gateway Max on-site. The MSP wants to manage all sites from a single Purple account but is concerned about security and how Purple's cloud will communicate back to the individual local controllers to authorize guest MAC addresses, given that the local gateways are behind dynamic public IPs with NAT.

The optimal architecture utilizes UniFi's official REST API with inbound port forwarding or a reverse proxy, combined with dynamic DNS (DDNS). For each hotel: 1) Configure a DDNS hostname on the Cloud Gateway Max (e.g., hotel01.mspdomain.com) so that the gateway's public IP is always trackable. 2) Set up a port forwarding rule on the gateway to forward inbound HTTPS traffic on a high, non-standard port (e.g., 10443) to the local gateway's management IP on port 443. 3) In the UniFi controller, navigate to Settings > Control Plane > Integrations and generate a unique API Key. 4) In the Purple Portal, configure a unique 'Venue' for each hotel, selecting the Ubiquiti UniFi integration. Enter the unique DDNS address with the forwarded port (e.g., hotel01.mspdomain.com:10443) and the specific API Key generated for that site. Finally, secure the inbound port forwarding on each gateway by restricting source IPs to Purple's public cloud IP ranges, preventing unauthorized access from the rest of the internet.

Examiner's Commentary: Using a high, non-standard port for port forwarding, combined with strict source IP whitelisting to only allow Purple's cloud IP blocks, mitigates the security risks of exposing the controller's API port to the public internet. This architecture avoids the need for expensive static public IPs at every site while maintaining robust, real-time MAC authorization capabilities.

Practice Questions

Q1. A network administrator has configured an external captive portal on a UniFi guest network. During testing, they notice that the captive portal splash page loads successfully, but after the guest enters their email address and clicks 'Connect', the browser hangs and eventually shows a timeout error. The client remains quarantined. What is the most likely cause of this issue, and how should it be investigated?

Hint: The portal page loaded, which means the DNS and walled garden are working. The failure happens *after* the guest submits their credentials.

View model answer

The most likely cause is a failure in the API authorization handshake between the Purple cloud and the UniFi Controller. Since the portal page loaded and the guest was able to interact with it, the DNS and Pre-Authorization Access (Walled Garden) configurations are correct. However, when the guest completes authentication, Purple attempts to send a secure REST API call (POST request) to the UniFi Controller to authorize the client's MAC address. If the UniFi Controller is behind a firewall, NAT, or on a private network without proper port forwarding, or if the API credentials (or API Key) are incorrect, the authorization request will fail or time out. To investigate: 1) Verify that the UniFi Controller's FQDN and port are publicly accessible from Purple's IP ranges. 2) Check the inbound firewall rules on the gateway protecting the UniFi Controller to ensure port 443 (or 8443) is open. 3) In the Purple Portal, verify that the UniFi integration settings contain the correct API Key or administrator credentials and that the controller URL is accurate. 4) Inspect the UniFi Controller's server.log file for any incoming connection attempts or API authentication errors from Purple's IPs.

Q2. An enterprise deployment requires setting up a guest network with an external captive portal. The network architect wants to use HTTPS for all captive portal traffic to prevent credential sniffing. They enable 'Use Secure Portal (HTTPS)' and 'Redirect Using Hostname' in UniFi, pointing to the external portal FQDN. However, when clients connect, their browsers immediately display a severe 'SSL Certificate Common Name Mismatch' or 'Certificate Not Trusted' warning, blocking access. How can this be resolved?

Hint: Think about which device is serving the initial redirect and what SSL certificate it is presenting to the client.

View model answer

This issue occurs because the UniFi Access Point or Controller is attempting to intercept an HTTPS request from the client and redirect it to the captive portal. When a client connects and tries to visit an HTTPS website (e.g., https://www.google.com), the AP's redirector intercepts the traffic. To perform the redirect over HTTPS, the AP must present an SSL certificate. Since the AP does not possess a valid SSL certificate for www.google.com, the client's browser detects a Man-in-the-Middle (MITM) condition and throws a severe SSL warning. To resolve this: 1) Ensure that the UniFi Controller itself has a valid, publicly trusted SSL certificate installed matching its configured FQDN. 2) In the UniFi guest network settings, disable 'Redirect HTTPS' (leave only HTTP redirection enabled). This prevents the AP from attempting to intercept HTTPS traffic. Instead, the network will rely on the client device's operating system Captive Portal Assistant (CPA), which tests connectivity using plain HTTP endpoints (e.g., http://captive.apple.com or http://connectivitycheck.gstatic.com). The AP can safely intercept these HTTP requests on port 80 and redirect them to the secure HTTPS URL of the Purple portal (https://portal.purplehotspot.com) without triggering any browser SSL warnings.

Q3. A hotel chain wants to deploy WPA3-Enterprise security for their VIP guest network while maintaining integration with Purple's analytics platform. The local IT team is unsure if they can use the standard External Portal Server captive portal redirection with WPA3-Enterprise. What is the correct architectural approach for this scenario?

Hint: WPA3-Enterprise uses 802.1X authentication, which occurs at the association phase, before an IP address is assigned. This is fundamentally different from an open SSID with a captive portal.

View model answer

WPA3-Enterprise (and WPA2-Enterprise) uses 802.1X authentication, which is fundamentally incompatible with standard captive portal web redirection. In an 802.1X network, authentication occurs at the association phase (Layer 2) using EAP methods (such as EAP-TLS or PEAP) before the client is assigned an IP address or allowed onto the network. Therefore, you cannot redirect a client to a web-based splash page. To integrate WPA3-Enterprise with Purple: 1) Shift from the 'External Portal Server' model to an External RADIUS model. 2) Configure a RADIUS Profile in the UniFi Network Application, entering Purple's Cloud RADIUS server IP addresses, authentication ports (typically 1812), accounting ports (typically 1813), and the shared secret. 3) Enable RADIUS Accounting and set an Interim Update Interval of 300 seconds. 4) Configure the VIP SSID to use WPA3 Enterprise and select the RADIUS Profile. When a VIP guest connects, their device authenticates directly against Purple's Cloud RADIUS server using their unique enterprise credentials or certificate. Purple's RADIUS server authorizes the connection and receives the accounting updates, allowing the venue to capture connection analytics, session duration, and data usage without requiring a web-based splash page.

Continue reading in this series

Captive Portal for Ruckus

This technical reference guide provides an authoritative integration playbook for deploying external captive portals on CommScope Ruckus SmartZone and Unleashed architectures. It guides network engineers through step-by-step configurations for Guest WLANs, WISPr redirection, RADIUS AAA server settings, and Walled Garden exceptions to deliver a secure, high-density guest WiFi solution.

Read the guide →

Captive Portal for Aruba

An authoritative technical reference guide for configuring Aruba Instant (IAP) and Aruba Central managed access points to redirect guest users to Purple's high-converting, secure external captive portal. This guide covers step-by-step guest SSID setup, external captive portal redirection, RADIUS server authentication and accounting parameters, walled garden exception lists, and WISPr support.

Read the guide →

Captive Portal for Cisco Meraki

An authoritative, intermediate-level technical reference guide for integrating Cisco Meraki MR access points with Purple's cloud captive portal. Covers step-by-step Meraki Dashboard configurations, RADIUS server settings (ports 1812/1813), walled garden wildcard domain exceptions, and session timeout parameters for high-performance guest WiFi deployments.

Read the guide →