Captive Portals

A captive portal displays a splash page when users connect to your WiFi network. Users must authenticate (via email, social login, voucher, or payment) before gaining internet access. IronWifi hosts and manages your captive portal in the cloud.

Quick Start

Navigate to Captive Portals > Add Captive Portal
Enter a name and select your network
Choose your vendor (access point brand)
Enable authentication providers (email, social login, etc.)
Copy the Splash Page URL to your controller
Configure the Walled Garden on your controller
Test by connecting to the WiFi network

How Captive Portals Work

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    User      │────▶│  Access      │────▶│   IronWifi   │
│   Device     │     │   Point      │     │   RADIUS     │
└──────────────┘     └──────────────┘     └──────────────┘
       │                                         │
       │ HTTP Request                            │
       ▼                                         ▼
┌──────────────┐                         ┌──────────────┐
│   Redirect   │◀────────────────────────│   Walled     │
│  to Splash   │                         │   Garden     │
└──────────────┘                         └──────────────┘
       │
       ▼
┌──────────────┐     ┌──────────────┐
│   Splash     │────▶│  Auth        │ (Google, Email, SMS, etc.)
│    Page      │     │  Provider    │
└──────────────┘     └──────────────┘
       │
       │ Success
       ▼
┌──────────────┐
│   Internet   │
│   Access     │
└──────────────┘

Creating a Captive Portal

Navigate to Captive Portals
Click Add Captive Portal
Configure the settings described below
Click Save

Basic Settings

Setting	Description
Name	Give your Captive Portal a descriptive name
Description	Optional description for your reference
Network	The network this portal belongs to (uses that network's RADIUS servers)
Vendor	Brand of your Access Points or Controller

Authentication Settings

Splash Page URL

This is the URL where your splash page is hosted. Configure this URL in your Controller settings as the External Captive Portal.

tip

The Splash Page URL is displayed in your Captive Portal settings after creation.

On Success Redirect

Define where users go after successful authentication:

Option	Description
Initially Requested URL	Return to the page they were trying to visit
Success Page	Show a custom success page
External URL	Redirect to a specific URL (include protocol, e.g., `https://www.example.com`)

Language

Select the language for internal error and notice messages.

Authentication Providers

Configure which authentication methods are available on your splash page:

Email - Users enter their email address
Social Login - Google, Facebook, LinkedIn, Twitter, Apple
SMS - Phone verification via text message
Vouchers - Pre-generated access codes
Username/Password - Traditional login
SAML - Enterprise single sign-on
Payment - Pay for access via Stripe, Braintree, PayPal

See Authentication Providers for detailed configuration.

Portal Pages

Customize the pages users see during authentication:

Splash Page - Initial landing page
Success Page - Shown after successful authentication
Error Page - Displayed when authentication fails
Terms Page - Terms and conditions

See Portal Pages for customization options.

Advanced Features

File Library

Upload and manage static files for your portal pages:

Logos and images
Custom CSS stylesheets
JavaScript files

Reference uploaded files using relative paths:

<img src="./logo.png">
<link type="text/css" href="custom.css" />

Cloud CDN

Enable Google Cloud CDN for faster loading of static files. This adds caching headers to improve performance globally.

Client Analytics

Collect detailed visitor information:

Screen resolution
Operating system
Browser and version
Installed fonts
Device type

Data is available in Reports.

MAC-Based Authentication

Allow returning users to auto-authenticate based on their device's MAC address:

MAC address is extracted from the URL
If the device was previously authenticated, access is granted automatically
Users can manage authorized devices in their profile
Administrators can deauthorize devices in the Console

note

If you delete a user, their MAC address associations are also deleted.

Purchase Confirmation

Enable to automatically send confirmation emails after successful access purchases.

Security Settings

IP Address Whitelist

Restrict access to the captive portal by IP range:

127.0.0.1, 10.0.2.0/24, 192.168.1.0/24

Leave empty for public access.

Webhook URL

Receive POST notifications after every successful authentication:

{
  "user_type": "new",
  "username": "john@example.com",
  "logindate": "2024-01-15T10:30:00Z",
  "request_url": "https://...",
  "ap_mac": "AA:BB:CC:DD:EE:FF",
  "client_mac": "11:22:33:44:55:66",
  "auth_provider_name": "email",
  "captive_portal_name": "Guest WiFi",
  "orig_response": {}
}

Webhook Integration Examples

Zapier Integration:

Create a Zap with "Webhooks by Zapier" trigger
Select "Catch Hook"
Copy the webhook URL to IronWifi
Connect to apps like:
- Google Sheets (log all logins)
- Mailchimp (add to mailing list)
- Slack (notify on new users)
- HubSpot (create contacts)

Custom Integration (Node.js):

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/ironwifi', (req, res) => {
  const { username, auth_provider_name, logindate } = req.body;

  // Log to database
  console.log(`New login: ${username} via ${auth_provider_name}`);

  // Send welcome email
  if (req.body.user_type === 'new') {
    sendWelcomeEmail(username);
  }

  // Add to CRM
  addToMailingList(username);

  res.status(200).send('OK');
});

app.listen(3000);

Python Flask Example:

from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhook/ironwifi', methods=['POST'])
def handle_webhook():
    data = request.json

    # Process authentication event
    username = data.get('username')
    provider = data.get('auth_provider_name')

    # Your custom logic here
    log_authentication(username, provider)

    return 'OK', 200

Webhook Behavior

Aspect	Details
Timeout	10 seconds - ensure your endpoint responds quickly
Retries	3 attempts with exponential backoff (1s, 5s, 30s)
Format	JSON POST request with `Content-Type: application/json`
Expected Response	HTTP 2xx status code

Webhook Troubleshooting

Webhook not triggering:

Verify the webhook URL is publicly accessible (not localhost)
Check URL includes https:// protocol
Ensure your server accepts POST requests
Review firewall rules allowing inbound connections

Webhook receiving but failing:

Return HTTP 200 status within 10 seconds
Process data asynchronously for slow operations
Log incoming requests to debug payload issues
Check your server logs for errors

Testing your webhook:

# Test with curl
curl -X POST https://your-server.com/webhook/ironwifi \
  -H "Content-Type: application/json" \
  -d '{
    "user_type": "new",
    "username": "test@example.com",
    "auth_provider_name": "email"
  }'

Common webhook errors:

Error	Cause	Solution
Connection timeout	Server unreachable	Check server is running and accessible
SSL certificate error	Invalid/expired cert	Install valid SSL certificate
500 Internal Server Error	Code exception	Check server logs, validate JSON parsing
401 Unauthorized	Auth required	Remove authentication or add API key handling

Controller Configuration

Your Captive Portal settings page displays information needed for controller configuration:

SAML Settings (if enabled)

Setting	Description
SAML ACS URL	Assertion Consumer URL for your Identity Provider
SAML Logout URL	Optional logout URL for IdP configuration
Entity Id	Globally unique name for this SAML entity

RADIUS Servers

IP addresses, ports, and shared secrets for Primary and Backup servers (same as Network settings).

Walled Garden

List of IP addresses and domains to add to your controller's pre-authorization access list. See Walled Garden Guide.

important

All visitors need access to the Splash Page URL, hosted at 107.178.250.42/32

Guest Manager

Configure how temporary user accounts are created during captive portal authentication.

Auto-Registration Settings

Setting	Description
Auto-create users	Automatically create user accounts when guests authenticate
Default group	Assign new users to a specific group with predefined policies
Username format	Use email, phone number, or generate unique ID
Password policy	Auto-generate or allow user-defined passwords

User Data Collection

Configure which information to collect during registration:

Field	Required	Notes
Email	Configurable	Primary identifier for most providers
Full Name	Optional	First/last name fields
Phone Number	Optional	Required for SMS authentication
Company	Optional	Useful for business venues
Custom Fields	Optional	Add your own fields (e.g., room number, department)

Account Policies

Setting	Description	Recommended
Account Expiration	How long until account is deleted	30-90 days
Session Duration	Max time per login session	24 hours
Max Sessions	Concurrent device limit	3-5 devices
Re-authentication	Require login after period	7 days

Data Privacy

For GDPR and privacy compliance:

Enable consent checkbox before data collection
Link to your privacy policy on splash page
Configure data retention period in account policies
Support data export and deletion requests

tip

Set account expiration to match your data retention policy to automatically comply with privacy regulations.

Session Management

Session Timeout

Configure how long users stay authenticated:

Setting	Description
Session Timeout	Maximum session duration (e.g., 24 hours)
Idle Timeout	Disconnect after inactivity (e.g., 30 minutes)
Session Limit	Maximum concurrent sessions per user

Bandwidth Limits

Control network usage per user:

Setting	Description
Download Limit	Maximum download speed (Mbps)
Upload Limit	Maximum upload speed (Mbps)
Data Cap	Maximum data transfer per session

Access Schedules

Restrict access to specific times:

Business hours only
Weekdays vs weekends
Custom schedules

Analytics & Reporting

Track captive portal usage in the IronWifi Console:

Available Reports

Report	Description
Authentications	Successful/failed login attempts
User Activity	Session duration, data usage
Provider Usage	Which auth methods are popular
Device Types	Mobile vs desktop breakdown
Peak Times	Busiest connection times

Accessing Reports

Navigate to Reports in the Console
Select Captive Portal category
Choose date range and filters
Export to CSV or PDF

Real-time Monitoring

View currently connected users
Monitor active sessions
Track bandwidth usage

Troubleshooting

Splash Page Not Loading

Verify 107.178.250.42/32 is in your Walled Garden
Check controller external captive portal URL is correct
Ensure HTTPS redirect is enabled on controller
Test direct access to splash URL in browser

Authentication Failing

Check IronWifi Console > Logs for error messages
Verify authentication provider credentials (OAuth keys, etc.)
Ensure all required domains are in Walled Garden
Test with different authentication method

Users Not Redirected

Verify captive portal is enabled on controller
Check client is on correct VLAN/SSID
Some apps bypass captive portal - test with browser
Check for DNS issues

Verify OAuth app credentials are correct
Check redirect URI matches IronWifi settings
Ensure social provider domains in Walled Garden
Test in incognito/private browser window

MAC Authentication Issues

Verify MAC address format matches controller
Check user has MAC authentication enabled
Ensure device was previously authenticated
Review MAC authorization logs

Mobile Device Behavior

Mobile devices handle captive portals differently. Understanding these behaviors helps troubleshoot issues.

Captive Network Assistant (CNA)

Most devices use a mini-browser to detect and display captive portals:

Device	CNA Behavior	Notes
iOS	Auto-opens popup browser	Limited functionality, no extensions
Android	Notification + popup browser	Varies by manufacturer
Windows	Notification to open browser	Click required
macOS	Auto-opens popup browser	Similar to iOS
ChromeOS	Notification + popup	Sign-in required prompt

iOS-Specific Issues

CNA limitations on iOS:

No access to cookies from main Safari
Social login popups may not work
Limited JavaScript support
Users may need to tap "Use Without Internet" and manually open Safari

Workaround for social login:

<!-- Add a link to open full Safari -->
<p class="cna-notice">
  Having trouble? <a href="{{splash_url}}" target="_blank">Open in Safari</a>
</p>

Detecting CNA browser:

// iOS CNA has limited window size
if (window.innerWidth < 400 && /CaptiveNetworkSupport/.test(navigator.userAgent)) {
  document.body.classList.add('cna-mode');
}

Android-Specific Issues

Common Android problems:

Some devices don't auto-detect captive portals
VPN apps may interfere with detection
"Always-on VPN" blocks captive portal

Solutions:

Instruct users to disable VPN temporarily
Provide manual URL to access splash page
Configure controller to use HTTP (not HTTPS) redirect initially

Apps Bypassing Captive Portal

Some apps bypass captive portal detection:

App Type	Behavior	Solution
VPN apps	Tunnel traffic, skip portal	User must disable VPN
Email apps	Background sync fails	User opens browser to authenticate
Some games	Direct socket connections	Block until authenticated
Banking apps	Certificate pinning fails	Authenticate via browser first

Best Practices for Mobile

Keep splash pages simple - Complex JS may fail in CNA
Test social login in CNA - May need "Open in browser" fallback
Provide manual URL - Display splash URL for manual access
Use responsive design - CNA browsers have small viewports
Avoid pop-ups - Many CNA browsers block them
Test on real devices - Simulators don't replicate CNA behavior

FAQ

How do I customize the splash page design?

See Portal Pages for customization options including the visual editor and HTML/CSS editing.

Can I use my own domain for the splash page?

Yes, contact IronWifi support to configure a custom domain with SSL certificate.

How do I require terms acceptance?

Enable the Terms page in Portal Pages and configure the checkbox requirement in your splash page settings.

Can users authenticate on multiple devices?

Yes, configure the session limit in Guest Manager settings. Users can also manage their authorized devices.

How do I set up paid WiFi access?

Enable a payment provider (Stripe, Braintree) in Authentication Providers and configure access plans with pricing.

For EU customers and GDPR compliance:

Ensure your splash page includes:

Clear consent checkbox - Users must actively opt-in
Privacy policy link - Accessible before authentication
Purpose explanation - What data is collected and why
Marketing opt-in - Separate checkbox for promotional emails

<div class="consent-section">
  <div class="checkbox-group">
    <input type="checkbox" id="privacy" required>
    <label for="privacy">
      I have read and agree to the
      <a href="/privacy-policy" target="_blank">Privacy Policy</a> *
    </label>
  </div>

  <div class="checkbox-group">
    <input type="checkbox" id="marketing">
    <label for="marketing">
      I agree to receive promotional emails (optional)
    </label>
  </div>
</div>

Data Retention

Configure data retention policies in IronWifi:

Data Type	Recommended Retention	Notes
Authentication logs	90 days	Required for security
User accounts	Until deletion request	GDPR right to erasure
Session data	30 days	Network troubleshooting
Marketing consent	Indefinitely	Proof of consent

User Rights Implementation

Support GDPR user rights:

Right to access: Users can view their data in profile
Right to erasure: Delete user accounts on request
Right to portability: Export user data as CSV/JSON
Right to rectification: Users can update their information

If using analytics or tracking:

<div id="cookie-notice" class="cookie-banner">
  <p>We use cookies to improve your experience.
     <a href="/cookie-policy">Learn more</a></p>
  <button onclick="acceptCookies()">Accept</button>
  <button onclick="declineCookies()">Decline</button>
</div>

Troubleshooting Flowchart

                    CAPTIVE PORTAL NOT WORKING
                              |
                              v
              +---------------+---------------+
              |                               |
              v                               v
    Splash page loads?                  No redirect?
              |                               |
         Yes  |  No                      Yes  |  No
              |   |                           |   |
              v   v                           v   v
         Check    Check                  Check    Check
         auth     walled                 CP is    DHCP/DNS
         providers garden                enabled  settings
              |   |                           |   |
              v   v                           v   v
    +--------------------+          +--------------------+
    | AUTH ISSUES        |          | REDIRECT ISSUES    |
    +--------------------+          +--------------------+
    |                    |          |                    |
    | - OAuth creds?     |          | - DNS redirect?    |
    | - Walled garden    |          | - HTTPS intercept? |
    |   domains?         |          | - Client on        |
    | - Provider         |          |   correct VLAN?    |
    |   enabled?         |          | - Firewall rules?  |
    +--------------------+          +--------------------+

    SPLASH PAGE NOT LOADING
              |
              v
    Is 107.178.250.42 in walled garden?
              |
         No   |   Yes
              |     |
              v     v
         Add it   Check controller
         and      captive portal
         retry    URL configuration
                        |
                        v
              Is URL exactly correct?
              (including https://)
                        |
                   No   |   Yes
                        |     |
                        v     v
                   Fix URL   Check DNS
                             resolution
                             from client

API & Programmatic Management

Manage captive portals programmatically via the IronWifi API.

Authentication

curl -X POST https://console.ironwifi.com/api/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "your@email.com", "password": "your-password"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

List Captive Portals

curl -X GET https://console.ironwifi.com/api/captive-portals \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Captive Portal Details

curl -X GET https://console.ironwifi.com/api/captive-portals/{id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Captive Portal

curl -X PUT https://console.ironwifi.com/api/captive-portals/{id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Portal Name",
    "redirect_url": "https://example.com"
  }'

List Authenticated Users

curl -X GET https://console.ironwifi.com/api/captive-portals/{id}/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

Disconnect User

curl -X DELETE https://console.ironwifi.com/api/sessions/{session_id} \
  -H "Authorization: Bearer YOUR_TOKEN"

API Rate Limits

Endpoint	Rate Limit
Authentication	10/minute
Read operations	100/minute
Write operations	30/minute

See API Documentation for complete reference.

Controller Configuration Guides

Configure your access point/controller for captive portal:

Ubiquiti

Vendor	Configuration Guide
UniFi Controller	UniFi Guide
UniFi Hotspot	UniFi Hotspot Guide

Cisco

Vendor	Configuration Guide
Meraki	Meraki Guide
Catalyst	Catalyst Guide
WLC	WLC Guide
Mobility Express	Mobility Guide

Aruba

Vendor	Configuration Guide
IAP (Instant)	Aruba IAP Guide
Instant On	Instant On Guide
Mobility Controller	Mobility Controller Guide

Ruckus

Vendor	Configuration Guide
SmartZone	SmartZone Guide
Ruckus Cloud	Ruckus Cloud Guide
Zone Director	Zone Director Guide
Ruckus Flex (Unleashed)	Ruckus Flex Guide

Other Vendors

Vendor	Configuration Guide
MikroTik	MikroTik Guide
FortiGate	FortiGate Guide
TP-Link Omada	Omada Guide
TP-Link EAP	EAP Guide
Juniper Mist	Mist Guide
pfSense	pfSense Guide
OPNsense	OPNsense Guide
Grandstream	Grandstream Guide
Cambium	Cambium Guide
NETGEAR	NETGEAR Guide
SonicWall	SonicWall Guide
Zyxel	Zyxel Guide
DrayTek	DrayTek Guide
Peplink	Peplink Guide
Teltonika	Teltonika Guide
D-Link Nuclias	D-Link Nuclias Guide
Proxim Wireless	Proxim Guide
WatchGuard	WatchGuard Guide
Alcatel-Lucent	Alcatel-Lucent Guide
CoovaChilli	CoovaChilli Guide

Quick Start​

How Captive Portals Work​

Creating a Captive Portal​

Basic Settings​

Authentication Settings​

Splash Page URL​

On Success Redirect​

Language​

Authentication Providers​

Portal Pages​

Advanced Features​

File Library​

Cloud CDN​

Client Analytics​

MAC-Based Authentication​

Purchase Confirmation​

Security Settings​

IP Address Whitelist​

Webhook URL​

Webhook Integration Examples​

Webhook Behavior​

Webhook Troubleshooting​

Controller Configuration​

SAML Settings (if enabled)​

RADIUS Servers​

Walled Garden​

Guest Manager​

Auto-Registration Settings​

User Data Collection​

Account Policies​

Data Privacy​

Session Management​

Session Timeout​

Bandwidth Limits​

Access Schedules​

Analytics & Reporting​

Available Reports​

Accessing Reports​

Real-time Monitoring​

Troubleshooting​

Splash Page Not Loading​

Authentication Failing​

Users Not Redirected​

Social Login Not Working​

MAC Authentication Issues​

Mobile Device Behavior​

Captive Network Assistant (CNA)​

iOS-Specific Issues​

Android-Specific Issues​

Apps Bypassing Captive Portal​

Best Practices for Mobile​

FAQ​

How do I customize the splash page design?​

Can I use my own domain for the splash page?​

How do I require terms acceptance?​

Can users authenticate on multiple devices?​

How do I set up paid WiFi access?​

GDPR & Privacy Compliance​

Data Collection Consent​

Example Consent Implementation​

Data Retention​

User Rights Implementation​

Cookie Notice​

Troubleshooting Flowchart​

API & Programmatic Management​

Authentication​

List Captive Portals​

Get Captive Portal Details​

Update Captive Portal​

List Authenticated Users​

Disconnect User​

API Rate Limits​

Controller Configuration Guides​

Ubiquiti​

Cisco​

Aruba​

Ruckus​

Other Vendors​

Related Topics​