Captive Portal for Ruckus

Executive Summary

Deploying a high-performance guest wireless network in enterprise venues requires a delicate balance between seamless user experience and robust technical security. For organizations utilizing CommScope Ruckus architectures—ranging from high-density stadiums and convention centres to expansive retail estates and hospitality groups—the captive portal serves as the primary gateway for user onboarding, compliance enforcement, and first-party data capture.

This guide delivers an authoritative, step-by-step playbook for integrating external captive portals with Ruckus SmartZone and Ruckus Unleashed controllers. By leveraging industry-standard Wireless Internet Service Provider roaming (WISPr) protocols, network engineers can implement reliable redirection, secure Remote Authentication Dial-In User Service (RADIUS) authentication, and granular Walled Garden configurations.

When paired with Purple's Guest WiFi and WiFi Analytics platform, this integration allows venue operators to capture critical visitor demographics, comply with international data regulations (such as GDPR and PCI DSS), and unlock powerful marketing automation. Whether deploying centralized Virtual SmartZone (vSZ) architectures in Hospitality and Transport hubs, or distributed AP-based Unleashed networks in Retail environments, this technical reference ensures a resilient, high-throughput deployment.

Technical Deep-Dive

To deploy a highly scalable guest network, engineers must understand the underlying communication standards that govern the captive portal flow. Ruckus architectures utilize the WISPr 2.0 standard to negotiate client redirection and authentication. WISPr defines how a wireless access point (AP) or controller intercepts unauthenticated HTTP/HTTPS traffic and redirects the client browser to an external portal web server.

The WISPr Authentication Flow

The external captive portal redirection process follows a strict sequence of network transactions. Understanding this flow is essential for troubleshooting and configuring upstream firewall policies:

1. Association: The guest client associates with the open, unencrypted Guest SSID. The AP assigns an IP address to the client via DHCP.
2. HTTP Probe: The client operating system fires an HTTP probe (e.g., Apple's Captive Network Assistant probe to captive.apple.com or Android's connectivity check to connectivitycheck.gstatic.com) to verify internet access.
3. HTTP 302 Redirect: The Ruckus AP or SmartZone controller intercepts this unauthenticated HTTP request. It responds with an HTTP 302 Redirect, forwarding the client's browser to the external portal URL (e.g., Purple's login page). This redirect URL is appended with critical query parameters, including the client's MAC address (client_mac), IP address (client_ip), AP MAC address (ap_mac), and the controller's Northbound Interface IP (nbiIP).
4. Portal Rendering: The client browser loads the external portal page. Unauthenticated traffic to the portal domain and its associated assets is permitted by the controller's Walled Garden policy.
5. User Authentication: The user completes the login requirements (e.g., social sign-on, SMS registration, form submission) on the portal.
6. RADIUS Access-Request: The external portal platform, acting as a RADIUS client, sends an Access-Request to the configured RADIUS Authentication Server (such as Purple's Cloud RADIUS infrastructure).
7. RADIUS Access-Accept: The RADIUS server validates the credentials and returns an Access-Accept packet containing session parameters (e.g., session timeout, bandwidth limits) to the Ruckus controller.
8. NBI Callback: The external portal makes an API call to the Ruckus controller's Northbound Interface (NBI) using WISPr credentials, instructing the controller to authorize the client's MAC address.
9. Internet Access: The controller transitions the client's state to "Authenticated", permitting full internet access subject to configured session policies.

Core Architecture Comparison

Depending on the scale of the venue, organizations deploy either CommScope Ruckus SmartZone (enterprise-scale, controller-based) or Ruckus Unleashed (distributed, controller-less) architectures. While both support WISPr-based external captive portals, their underlying configuration paths and capabilities differ significantly:

Implementation Guide

This step-by-step implementation guide walks network engineers through configuring an external captive portal on Ruckus SmartZone and Ruckus Unleashed controllers.

Part A: Ruckus SmartZone Configuration

Step 1: Configure RADIUS AAA Servers

To authenticate guest users against an external database, you must first define the RADIUS Authentication and Accounting servers.

1. Navigate to Services & Profiles > Authentication and select the Proxy (SZ Authenticator) tab.
2. Select your target Zone and click Create.
3. Configure the following parameters:
   • Name: Purple_RADIUS_Auth
   • Service Protocol: RADIUS
   • Primary Server IP: Enter the IP address provided in your Purple Admin Console.
   • Port: 1812
   • Shared Secret: Enter your Purple RADIUS Shared Secret.
   • Backup RADIUS: Enabled (Configure the secondary IP, Port 1812, and the same shared secret for high availability).
4. Click OK to save.
5. Navigate to Services & Profiles > Accounting and click Create under the Proxy (SZ Authenticator) tab.
6. Configure the following parameters:
   • Name: Purple_RADIUS_Acct
   • Service Protocol: RADIUS Accounting
   • Primary Server IP: Enter the IP address provided in your Purple Admin Console.
   • Port: 1813
   • Shared Secret: Enter your Purple RADIUS Shared Secret.
   • Backup RADIUS: Enabled (Configure the secondary IP, Port 1813, and the same shared secret).
7. Click OK to save.

Step 2: Configure the Hotspot WISPr Portal Profile

The Hotspot WISPr profile defines the redirection behavior and Walled Garden rules.

1. Navigate to Services & Profiles > Hotspots & Portals > Hotspot (WISPr).
2. Select your target Zone and click Create.
3. In the General Options section, configure:
   • Portal Name: Purple_WISPr_Portal
   • WISPr Smart Client Support: None
   • Login URL: Select External and enter the primary redirect URL provided by Purple (e.g., https://login.purple.ai/start).
   • Redirect MAC Format: AA:BB:CC:DD:EE:FF (This format is critical for Purple's database parsing).
4. In the Start Page section, configure:
   • Select Redirect to the following URL and enter: https://login.purple.ai/success.php
5. In the Session Options section, configure:
   • Session Timeout: 1440 minutes (24 hours, or match your corporate policy).
   • Grace Period: 60 minutes (allows users to reconnect within 1 hour without re-authenticating).
6. Click OK to save the profile.

Step 3: Define Walled Garden Exceptions

The Walled Garden allows unauthenticated clients to resolve DNS and download assets from specific domains required to load the splash page and authenticate.

1. Edit your newly created Purple_WISPr_Portal profile.
2. Scroll down and click the + sign to expand the Walled Garden section.
3. Add the following mandatory domains. Note that Ruckus SmartZone requires the wildcard format *.domain.com:
   • *.purple.ai (Core portal and redirection domain)
   • *.cloudfront.net (CDN for loading stylesheet and JavaScript assets)
   • *.apple.com and captive.apple.com (To manage Apple Captive Network Assistant behavior)
   • *.googleapis.com and *.gstatic.com (For Google API and asset delivery)
4. Add any social media domains if you enable social login (e.g., *.facebook.com, *.facebook.net for Facebook login).
5. Click OK to save.

Step 4: Configure the Guest Wireless LAN (WLAN)

Now, bind the RADIUS servers and Hotspot profile to a new SSID.

1. Navigate to Wireless LANs and select your target Zone.
2. Click Create to build a new WLAN.
3. Configure the General Options:
   • Name: Guest_WiFi
   • SSID: !Free_Venue_WiFi
4. Configure the Security Options:
   • Authentication Type: Hotspot (WISPr)
   • Method: Open
   • Encryption Options: None
5. Expand the Hotspot Portal section:
   • Hotspot (WISPr) Portal: Select Purple_WISPr_Portal.
   • Authentication Service: Select Purple_RADIUS_Auth.
   • Accounting Service: Select Purple_RADIUS_Acct.
   • Send Interim Update: Set to 5 minutes (essential for real-time session tracking).
6. Expand the RADIUS Options:
   • NAS ID: Set to User-defined and enter your Purple-assigned venue ID.
   • Called Station ID: Select AP MAC.
   • Single Session ID: ON (Prevents session duplication across APs).
7. Click OK to deploy the WLAN.

Step 5: Enable WISPr Northbound Interface (NBI)

The NBI allows Purple to communicate back to the SmartZone to authorize clients.

1. Navigate to Administration > External Services > WISPr Northbound Interface.
2. Check the box to Enable Northbound Interface support.
3. Define a Username and Password (e.g., purple_nbi / SecureNbiPassword123!).
4. Enter these credentials into the Purple Admin Console under Integrations > Ruckus SmartZone.

Step 6: Disable MAC/IP Encryption (CRITICAL CLI STEP)

By default, SmartZone encrypts MAC addresses in the redirect URL. You must disable this so Purple can read client MACs.

1. Open an SSH session to your SmartZone controller management IP.
2. Log in with your administrator credentials.
3. Execute the following commands:

   ruckus> enable
   ruckus# config
   ruckus(config)# no encrypt-mac-ip
   ruckus(config)# end
   ruckus# write memory
   

Part B: Ruckus Unleashed Configuration

For smaller venues utilizing a controller-less Unleashed architecture, configure the captive portal via the master AP web interface.

Step 1: Define AAA Servers

1. Navigate to Admin & Services > Services > AAA Servers.
2. Click Create New to add the RADIUS Authentication Server:
   • Name: Purple_Auth
   • Type: RADIUS
   • IP Address: Enter Purple's RADIUS IP.
   • Port: 1812
   • Shared Secret: Enter your Purple RADIUS Shared Secret.
3. Click OK.
4. Click Create New to add the RADIUS Accounting Server:
   • Name: Purple_Acct
   • Type: RADIUS Accounting
   • IP Address: Enter Purple's RADIUS IP.
   • Port: 1813
   • Shared Secret: Enter your Purple RADIUS Shared Secret.
5. Click OK.

Step 2: Configure Hotspot Service

1. Navigate to Admin & Services > Services > Hotspot Services.
2. Click Create New.
3. Under the General tab:
   • Name: Purple_Hotspot
   • Login URL: Enter your Purple redirect URL.
   • Start Page: Select Redirect to the following URL and enter https://login.purple.ai/success.php.
4. Under the Authentication tab:
   • Authentication Server: Select Purple_Auth.
   • Accounting Server: Select Purple_Acct.
   • Interim Update: Set to 5 minutes.
5. Under the Walled Garden tab:
   • Add domain-level entries (e.g., purple.ai, cloudfront.net, gstatic.com). Note that Unleashed does not require the asterisk wildcard prefix; standard domain-level matching is applied automatically.
6. Click OK to save.

Step 3: Assign Hotspot Service to WLAN

1. Navigate to Wi-Fi Networks and click Create.
2. Set Name and SSID to your guest network name.
3. Set Usage Type to Hotspot Service.
4. Select Purple_Hotspot from the list of services.
5. Click OK to publish the SSID across all Unleashed APs.

Best Practices

To ensure maximum performance, security, and regulatory compliance, network architects should implement the following industry-standard best practices:

1. Granular Guest VLAN Segmentation

Never map guest traffic to the native or management VLAN. Always isolate guest clients on a dedicated, non-routable VLAN (e.g., VLAN 100). Implement strict Access Control Lists (ACLs) on the upstream switch or firewall to block guest traffic from reaching corporate subnets, point-of-sale (POS) systems, and IoT infrastructure. This segmentation is a core requirement for PCI DSS compliance.

2. High-Density RF Optimization

In high-density environments like stadiums, conference centres, and large retail hubs, RF tuning is critical. Disable lower legacy data rates (e.g., disable 802.11b rates below 12 Mbps) to force clients onto faster rates, reducing airtime contention. Enable Band Steering to direct dual-band client devices to the 5 GHz and 6 GHz spectrum, preserving the highly congested 2.4 GHz band for legacy devices.

3. Dynamic Walled Garden Management

Keep your Walled Garden as lean as possible. Overly permissive walled gardens (such as adding large IP subnets like 172.217.0.0/16) can allow unauthenticated users to bypass the captive portal and access external services (like Google Search or YouTube) without logging in. Regularly audit your walled garden domains, especially after enabling new social login providers.

4. Secure Session Management

Set reasonable session timeouts (e.g., 1440 minutes / 24 hours) and grace periods (e.g., 60 minutes). A well-configured grace period prevents "portal fatigue" by allowing users who temporarily lose WiFi coverage (e.g., stepping outside a hotel lobby) to reconnect seamlessly without being forced to re-authenticate.

5. Regulatory Compliance and Security

Deploying public guest WiFi exposes venues to legal risks. Ensure your captive portal integration complies with local regulations:

• GDPR / CCPA: Ensure the splash page displays clear terms of service and privacy policies, requiring active opt-in consent for marketing communications.
• WPA3-Transition Mode: While guest networks are typically open, consider enabling WPA3-Transition mode with Opportunistic Wireless Encryption (OWE) to encrypt wireless traffic between the client and the AP without requiring a pre-shared key, protecting guests from passive eavesdropping.
• Web Content Filtering: Upstream DNS servers (such as Cisco Umbrella or Cloudflare Families) should be configured to block malicious domains, adult content, and illegal file-sharing traffic on the guest VLAN.

Troubleshooting & Risk Mitigation

When deploying external captive portals on Ruckus hardware, engineers commonly encounter a predictable set of configuration and network path issues. Use this structured troubleshooting framework to resolve deployment bottlenecks.

Common Failure Modes and Resolution Paths

Issue 1: Guest devices are not redirected to the captive portal page.

• Root Cause A: DNS Resolution Failure. Unauthenticated clients must be able to resolve DNS queries before redirection. If the client cannot resolve login.purple.ai, the redirect will fail.
  • Resolution: Verify that the DHCP scope assigned to the guest VLAN provides valid, public DNS servers (e.g., 1.1.1.1 or 8.8.8.8). Ensure the upstream firewall permits UDP port 53 traffic from the guest subnet to the internet pre-authentication.
• Root Cause B: Firewall blocking Port 9080/9443. SmartZone requires specific ports open to load the splash page.
  • Resolution: Ensure that TCP port 9080 (HTTP) or 9443 (HTTPS) is permitted through any local firewalls.
• Root Cause C: Walled Garden misconfiguration. The redirect URL itself might be blocked.
  • Resolution: Ensure *.purple.ai is explicitly defined in the Hotspot WISPr Walled Garden.

Issue 2: Guests can view and complete the login page, but cannot access the internet after clicking "Connect".

• Root Cause A: NBI Communication Failure. The external portal cannot send the authorization API call back to the SmartZone controller.
  • Resolution: Verify that the SmartZone's Northbound Interface (NBI) is enabled and that the credentials entered in the Purple Admin Console match the controller configuration. Ensure your edge firewall permits inbound TCP port 9080 (or 9443) traffic from Purple's public IP range to the SmartZone management IP.
• Root Cause B: RADIUS Authentication Failure. The controller is rejecting the RADIUS Access-Accept or has not received it.
  • Resolution: Navigate to Services & Profiles > Authentication on the SmartZone, select your RADIUS server, and click Test AAA. Enter test credentials to verify connectivity. If the test fails, verify the RADIUS IP, port 1812, and the Shared Secret. Ensure UDP ports 1812 and 1813 are permitted outbound on your edge firewall.

Issue 3: Apple iOS devices do not display the Captive Network Assistant (CNA) mini-browser automatically.

• Root Cause: Apple CNA Bypass Enabled or Walled Garden too permissive. If Apple's test domain is allowed in the walled garden, iOS assumes it has direct internet access and suppresses the CNA.
  • Resolution: Ensure that captive.apple.com is NOT fully bypassed in your walled garden if you want to force the CNA to appear. Conversely, if your policy is to bypass the CNA and force users to open a standard browser, ensure Bypass CNA is turned ON in the WLAN configuration.

Network Port and Protocol Requirements

To ensure seamless communication between the Ruckus controller, client devices, and the external portal, verify that the following ports are permitted on your network firewalls:

ROI & Business Impact

While network engineers focus on packet flows and port configurations, IT directors and CTOs must justify the investment in enterprise guest WiFi. Integrating Ruckus high-density hardware with Purple's WiFi Analytics platform transforms a cost-centre network into a high-value business asset, delivering measurable return on investment (ROI).

1. First-Party Data Capture at Scale

In industries like Retail and Hospitality , understanding customer demographics is a primary driver of business growth. A standard open SSID captures zero visitor data. By implementing Purple's captive portal, venues achieve average login completion rates of 25% to 40%. This allows operators to legally capture verified email addresses, phone numbers, and social profiles.

2. Hyper-Localized Marketing and Engagement

By pairing Ruckus's precise location services with Purple's marketing engine, venues can trigger automated, real-time campaigns based on physical presence. For example, a retail brand can trigger a targeted SMS coupon to a guest who has been browsing a specific department for more than 15 minutes, or a hotel can send a welcome email with a link to book spa services immediately after the guest connects to the lobby WiFi.

3. Operational Efficiency and Venue Insights

Integrating captive portals with location analytics delivers powerful operational intelligence. Venue directors can monitor:

• Footfall and Dwell Time: Measure the exact number of visitors, how long they stay, and their pathing through the physical space.
• Loyalty and Return Rates: Identify new vs. returning visitors to evaluate the impact of marketing campaigns and operational changes.
• Staff Optimization: Align staffing levels with real-time visitor density maps, reducing overhead during off-peak hours and improving customer service during peak times.

Business Impact Matrix

The table below outlines typical business outcomes across core verticals following the deployment of a Ruckus and Purple integrated guest WiFi network:

By aligning technical excellence in wireless engineering with strategic business goals, the Ruckus and Purple integration delivers a secure, compliant, and highly profitable enterprise network infrastructure.

References

• [1] CommScope Ruckus SmartZone Access Services Guide
• [2] Ruckus SmartZone RADIUS Authentication Deployment Guide
• [3] Ruckus Unleashed Hotspot WISPr Configuration Guide
• [4] Cisco Wireless APs: 2026 Guide to Products & Deployment
• [5] 10 Best Network Access Control (NAC) Solutions for 2026
• [6] WiFi in Schools: The 2026 Administrator & IT Guide
• [7] How to Implement 802.1X Authentication with Cloud RADIUS