UniFi Hotspot (Network v8/v9)

Set up IronWifi external captive portal on UniFi Network v8 or v9 controllers including UDM, UDM-Pro, Dream Router, and Cloud Key Gen2. This guide covers hotspot portal configuration, pre-authorization access, RADIUS integration, and traffic management for secure guest WiFi networks.

Classic UI / Network v7

For UniFi Controller v5.x, v6.x, or v7.x with the classic interface, see UniFi Controller Guide.

Prerequisites

In UniFi:

• UniFi Network v8.x or v9.x running on a supported device (see table below)
• Controller accessible from the internet
• Owner or Super Admin credentials

In IronWifi Console (complete these first):

1. Create a Network and note the RADIUS details (IPs, ports, shared secret)
2. Create a Captive Portal with:
   • Vendor: Ubiquiti Networks
   • Controller URL: See port requirements below
   • Credentials: UniFi admin username and password
3. Note the Splash Page URL displayed after saving

Controller URL by Device Type

Device	Port	Example URL
UDM / UDM-Pro / UDM-SE / UDR	443	https://public_ip
Cloud Key Gen2	8443	https://public_ip:8443
Self-hosted	8443	https://public_ip:8443

Controller URL Requirements

IronWifi must reach your controller to authorize guests. This requires:

• A public IP address (not private like 192.168.x.x)
• Port forwarding if behind another router
• Firewall rules allowing inbound connections

Supported Hardware

Device	Notes
Dream Machine (UDM)	Built-in controller, port 443
Dream Machine Pro (UDM-Pro)	Built-in controller, port 443
Dream Machine SE (UDM-SE)	Built-in controller, port 443
Dream Router (UDR)	Built-in controller, port 443
Cloud Key Gen2 / Gen2 Plus	External controller, port 8443
Self-hosted (Linux/Windows/Docker)	Port 8443
UniFi Express (UX)	Limited hotspot features

---

UniFi Network Configuration

Access your UniFi Network console via:

• Direct IP: https://console_ip
• UniFi.ui.com (remote access)

Step 1: Create Guest Network (VLAN)

1. Navigate to Settings → Networks
2. Click Create New
3. Configure:

Setting	Value	Notes
Name	Guest	Your choice
Router	(select your router)
Gateway IP/Subnet	Auto or custom (e.g., 10.100.0.1/24)
VLAN ID	Auto or custom (e.g., 100)	Recommended for isolation
Domain Name	(leave default)
DHCP Mode	DHCP Server
DHCP Range	Auto or custom

4. Expand Advanced (optional):

   • Isolation: Enable to prevent guest-to-guest communication
   • Allow Internet Access: Ensure enabled

5. Click Add

Step 2: Create WiFi Network

1. Navigate to Settings → WiFi
2. Click Create New
3. Configure:

Setting	Value	Notes
Name	Guest WiFi	SSID users will see
Password	(leave empty)	Open network for captive portal
Network	Guest	Select network created above

4. Expand Advanced Configuration:

Setting	Value
WiFi Band	2.4 GHz and 5 GHz (or your preference)
Band Steering	Prefer 5G (recommended)
BSS Transition	Enabled
Multicast Enhancement	Enabled

Step 3: Enable Hotspot Portal

In the WiFi settings, scroll to Hotspot Portal:

1. Toggle Hotspot Portal to On
2. Configure:

Setting	Value	Notes
Landing Page	External Portal Server	For IronWifi
External Portal	Custom
IPv4 Address	107.178.250.42	IronWifi splash page
Use Secure Portal	Enabled	Recommended
Redirect HTTPS	Disabled	Can cause issues
Redirect Hostname	(enter your splash hostname)	From IronWifi Console

3. Click Apply Changes

Step 4: Configure Hotspot Settings

Navigate to Settings → Hotspot:

Landing Page Tab

Setting	Value
Type	External
Template	Custom
IPv4 Address	107.178.250.42
Use Secure Portal	Enabled

Pre-Authorization Tab

Pre-authorization allows unauthenticated users to reach specific domains (needed for the splash page and social login).

Required Entry

Always add the IronWifi server:

107.178.250.42

Additional Entries by Authentication Provider

Only add entries for authentication methods you've enabled in IronWifi:

Provider	Required Pre-Authorization Entries
Google	*.google.com, *.googleapis.com, *.gstatic.com, accounts.google.com
Facebook	*.facebook.com, *.fbcdn.net, connect.facebook.net, facebook.com
LinkedIn	*.linkedin.com, *.licdn.com, linkedin.com
Twitter/X	*.twitter.com, *.twimg.com, twitter.com, *.x.com, x.com
Apple	*.apple.com, *.icloud.com, appleid.apple.com
Microsoft/Azure AD	*.microsoft.com, *.microsoftonline.com, *.msftauth.net, *.msauth.net, login.microsoftonline.com
Stripe	*.stripe.com, js.stripe.com
PayPal	*.paypal.com, *.paypalobjects.com
Twilio (SMS)	*.twilio.com

To add entries: Click Add Entry, enter the domain, and click Apply Changes.

Session Settings

Setting	Recommended Value	Notes
Session Timeout	480 minutes	Time before re-auth required
Block Clients	Off	Unless needed

Step 5: Traffic Management (Optional)

Navigate to Settings → Traffic Management:

Per-Client Bandwidth Limits

1. Click Add Rule
2. Configure:
   • Name: Guest Bandwidth Limit
   • Target: Guest network
   • Download Limit: 10 Mbps
   • Upload Limit: 5 Mbps

Traffic Rules

Create rules to control guest traffic:

1. Allow DNS before auth:

   • Already handled by default, but verify guests can resolve DNS

2. Block local network access:

   • Create rule to block guest → LAN traffic
   • Allows guests to reach internet only

---

Advanced Configurations

The following configurations are optional and depend on your specific requirements.

RADIUS Configuration (for WPA-Enterprise)

If using WPA-Enterprise authentication:

1. Navigate to Settings → Profiles → RADIUS
2. Click Create New
3. Configure:

Setting	Value
Profile Name	IronWifi RADIUS
Authentication Server
- IP Address	Primary IP from IronWifi
- Port	1812
- Shared Secret	From IronWifi
Accounting Server
- IP Address	Primary IP from IronWifi
- Port	1813
- Shared Secret	From IronWifi
Interim Update Interval	300

4. Click Add

WPA-Enterprise WiFi Setup

For 802.1X authentication without captive portal:

1. Navigate to Settings → WiFi
2. Create or edit network
3. Configure:

Setting	Value
Security Protocol	WPA2/WPA3 Enterprise
RADIUS Profile	IronWifi RADIUS
Hotspot Portal	Off

Dynamic VLAN Assignment

IronWifi can assign VLANs based on user attributes:

1. Create multiple VLANs in UniFi Networks
2. Configure RADIUS profile with VLAN tagging enabled
3. In IronWifi, configure user groups with VLAN IDs
4. Users will be placed in VLANs based on their group

Client Isolation Settings

Navigate to Settings → Networks → Edit Guest Network:

Setting	Description
Network Isolation	Prevents access to other networks
Client Device Isolation	Prevents guest-to-guest communication

Both recommended for guest networks.

Multiple SSIDs with Different Portals

Use SSID-based routing for different splash pages:

1. Create multiple Captive Portals in IronWifi
2. Use the router splash page method (see Classic UniFi guide)
3. Each SSID redirects to its designated portal URL

---

UniFi Device-Specific Notes

Dream Machine (UDM/UDM-Pro/UDM-SE)

• Controller Port: 443 (not 8443)
• API Endpoint: Automatically detected by IronWifi
• Port Forwarding: Configure in Network → Port Forwarding if UDM is behind another router

Dream Router (UDR)

• Similar to UDM configuration
• Limited to smaller deployments
• Same port (443) as other Dream Machine products

Cloud Key Gen2

• Controller Port: 8443
• Ensure Cloud Key has stable internet
• Consider static IP or DDNS for reliable connectivity

UniFi Express (UX)

• Limited hotspot features
• May require Network v9.x
• Check release notes for captive portal support

Self-Hosted Controller (Docker/Linux/Windows)

• Controller Port: 8443 (default)
• Ensure firewall allows inbound 8443/TCP
• Use static IP or DDNS hostname
• Keep controller updated

---

Testing and Verification

After completing the configuration steps above, verify everything works correctly.

Test Captive Portal Flow

1. Connect a device to the guest WiFi
2. Open a browser and navigate to http://example.com
3. Verify redirect to IronWifi splash page
4. Complete authentication
5. Verify internet access is granted
6. Check client shows as authorized in UniFi

Verify Controller Connection

In IronWifi Console:

1. Navigate to your Captive Portal settings
2. Check Controller Status shows "Connected"
3. If showing errors, verify URL and credentials

Check UniFi Client List

1. Navigate to Client Devices in UniFi
2. Find your test device
3. Verify status shows authorized/connected
4. Check the device is on the correct network

Review Authentication Logs

In IronWifi:

1. Navigate to Reports → Authentications
2. Look for recent authentication attempts
3. Verify status shows "Success"

In UniFi:

1. Navigate to System → System Log
2. Filter for hotspot events
3. Look for authorization entries

---

Troubleshooting

If testing reveals issues, use this section to diagnose and resolve common problems.

Hotspot Portal Not Showing

Symptom	Cause	Solution
No redirect	Hotspot Portal disabled	Enable in WiFi settings
Wrong page	Incorrect External Portal IP	Set to 107.178.250.42
HTTPS warnings	Secure Portal issues	Enable "Use Secure Portal" with hostname
Cached session	Previous authorization	Use incognito or different device

Verification steps:

1. Verify Hotspot Portal is enabled on the WiFi network
2. Check External Portal is set to Custom with IronWifi IP
3. Confirm Pre-Authorization includes 107.178.250.42
4. Test from a device that has never connected

Controller Connection Errors

Authentication Failed

Cause: Invalid credentials or insufficient permissions

Solutions:

1. Verify username and password
2. Ensure account has Owner or Super Admin role
3. Create dedicated admin account:
   • Navigate to Settings → Admins
   • Add new admin with appropriate permissions
4. Update credentials in IronWifi

Connection Timeout / Gateway Error

Cause: IronWifi cannot reach controller

Solutions:

1. Verify public IP: Ensure you're using public, not private IP
2. Check port:
   • UDM/UDR: Port 443
   • Cloud Key/Self-hosted: Port 8443
3. Configure port forwarding (if behind router):
   • UDM: Forward external 443 → UDM IP:443
   • Cloud Key: Forward external 8443 → CK IP:8443
4. Enable Proxy option: Use if firewall blocks Google Cloud IPs
5. Test accessibility: Try accessing controller URL from external network

Authorization Not Completing

Symptom	Cause	Solution
Stuck on splash	API authorization failed	Check controller connection
Returns to splash	Session not created	Verify controller credentials
Partial access	Walled garden incomplete	Add all required domains

Verification steps:

1. Check IronWifi Controller Status
2. Review IronWifi authentication logs for errors
3. Check UniFi System Log for related events

Social Login Issues

Symptom	Cause	Solution
OAuth page blank	Missing pre-authorization	Add provider domains
Login fails	OAuth app misconfigured	Check IronWifi OAuth settings
Popup blocked	CNA browser limitation	Open in full browser

Verification steps:

1. Verify all provider domains in Pre-Authorization
2. Test in Safari/Chrome, not CNA popup
3. Check OAuth credentials in IronWifi

Version-Specific Issues

v8 to v9 Migration Issues

If hotspot stopped working after update:

1. Re-check Hotspot Portal settings (may have reset)
2. Verify Pre-Authorization entries exist
3. Re-enter External Portal IP
4. Check WiFi network still has Hotspot enabled

New UI Layout Changes

UniFi frequently updates their interface:

1. Settings may move between versions
2. Check UniFi release notes for changes
3. Use search within settings to find options
4. Some features may be in "Advanced" sections

---

Version Differences

Feature	v7 (Classic)	v8	v9
Hotspot location	Guest Control	Settings → Hotspot	Settings → Hotspot
Pre-auth access	Access Control	Pre-Authorization	Pre-Authorization
RADIUS profiles	Per-SSID	Centralized	Centralized
External portal	Custom Portal	External Portal Server	External Portal Server
Traffic rules	Firewall Rules	Traffic Management	Traffic Management

---

Migration Notes

From Classic UI (v7) to New UI (v8/v9)

1. Document existing settings before upgrading
2. Settings to reconfigure:
   • Hotspot Portal settings (new location)
   • Pre-Authorization entries
   • RADIUS profiles
3. Test after migration - some settings may not carry over
4. IronWifi adjustments - usually none required if using same controller URL

From Self-Hosted to Dream Machine

1. Export user data if needed
2. Reconfigure IronWifi with new controller URL (port 443)
3. Reconfigure Hotspot Portal settings
4. Test authentication flow

---

Best Practices

Security

• Use dedicated admin account for IronWifi
• Enable network isolation for guests
• Place guests on dedicated VLAN
• Keep UniFi firmware updated
• Use strong RADIUS shared secret

Performance

• Set reasonable bandwidth limits
• Enable Band Steering for better distribution
• Use 5GHz where possible
• Monitor client counts per AP

User Experience

• Set session timeout to 8+ hours
• Offer multiple authentication options
• Test on various devices
• Provide clear splash page instructions

Maintenance

• Monitor controller connection status regularly
• Review authentication logs
• Subscribe to UniFi release notes
• Document your configuration

---

Quick Reference

Required Settings Summary

Setting	Location	Value
Hotspot Portal	WiFi → Advanced	Enabled
External Portal	WiFi → Hotspot Portal	Custom, 107.178.250.42
Pre-Authorization	Hotspot → Pre-Authorization	107.178.250.42 + providers
Controller URL	IronWifi	https://public_ip[:port]

Controller Ports by Device

Device	Port
UDM / UDM-Pro / UDM-SE / UDR	443
Cloud Key Gen2	8443
Self-hosted	8443

IronWifi Proxy IPs

35.184.225.240
35.201.240.80
35.195.230.167

Navigation Paths

Configuration	Path
WiFi Networks	Settings → WiFi
Hotspot Settings	Settings → Hotspot
Networks (VLANs)	Settings → Networks
RADIUS Profiles	Settings → Profiles → RADIUS
Traffic Management	Settings → Traffic Management
Client Devices	Client Devices (sidebar)
System Logs	System → System Log
Admin Accounts	Settings → Admins

Related Topics

• UniFi Controller (Classic)
• UniFi Passpoint Configuration
• Captive Portals Overview
• Authentication Providers
• Walled Garden Guide