Ubiquiti UniFi

Configure your UniFi Controller (Classic UI / Network v7 and earlier) to use IronWifi's RADIUS authentication and external captive portal. This guide walks you through RADIUS server configuration, guest control settings, and walled garden setup to deliver a seamless WiFi guest experience with customizable splash pages.

UniFi Network v8/v9

For the newer UniFi Network interface (v8, v9, or UniFi OS Console), see UniFi Hotspot Guide.

Prerequisites

In UniFi:

• UniFi Controller v5.x, v6.x, or v7.x installed and running
• Controller accessible from the internet (public IP or port forwarding on port 8443)
• Administrator 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: https://your_public_ip:8443 (must be public IP, not 192.168.x.x)
   • Credentials: UniFi admin username and password
3. Note the Splash Page URL displayed after saving

Controller URL Requirements

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

• A public IP address (not private like 192.168.x.x, 172.16.x.x, or 10.x.x.x)
• Port forwarding if controller is behind a router: External 8443 → Controller IP:8443
• Firewall rules allowing inbound TCP on port 8443

---

UniFi Controller Configuration

Step 1: Create Guest Wireless Network

UniFi 6.0+ Users

If running UniFi 6.0 or newer with the new UI, disable it during setup: System Settings → Disable "New Settings" or "New User Interface"

1. Log into UniFi Controller
2. Click Settings (gear icon, bottom left)
3. Navigate to Wireless Networks
4. Click Create New Wireless Network
5. Configure:

Setting	Value	Notes
Name/SSID	Guest WiFi	Your choice
Enabled	On
Security	Open	Required for captive portal
Guest Policy	Enabled	Required for captive portal
VLAN	(Optional)	See VLAN section below

6. Click Save

Step 2: Configure Guest Control

Navigate to Settings → Guest Control

Guest Policies

Setting	Value	Notes
Enable Guest Portal	Enabled
Authentication	External Portal Server
Custom Portal	107.178.250.42	IronWifi splash page IP
Use Secure Portal	Enabled	Recommended
Redirect using hostname	Enabled
Hostname	Your splash page hostname	From IronWifi Console
Enable HTTPS Redirection	Disabled	Can cause redirect loops

Landing Page Settings

Setting	Recommended Value
Redirect	To the originally requested URL
Expiration	480 minutes (8 hours)
Landing Page Enabled	Disabled

Step 3: Configure Pre-Authorization Access (Walled Garden)

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

Navigate to Access Control → Pre-Authorization Access and add entries.

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

tip

UniFi supports wildcard entries (*.domain.com), making configuration easier than some other vendors.

Step 4: Configure Bandwidth and Session Limits (Optional)

Under Guest Control → Access Control:

Setting	Recommended	Notes
Download Bandwidth Limit	5000 Kbps	Adjust based on needs
Upload Bandwidth Limit	2000 Kbps	Adjust based on needs
Data Transfer Limit	Unlimited	Or set per-session cap

---

Advanced Configurations

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

VLAN Configuration

Isolate guest traffic on a dedicated VLAN:

Step 1: Create Guest Network

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

Setting	Value
Name	Guest Network
Purpose	Corporate
VLAN ID	100 (or your choice)
Gateway/Subnet	10.100.0.1/24
DHCP Mode	DHCP Server
DHCP Range	10.100.0.10 - 10.100.0.200

4. Click Save

Step 2: Assign VLAN to Guest SSID

1. Navigate to Settings → Wireless Networks
2. Edit your guest SSID
3. Under Network, select the guest network created above
4. Click Save

Client Isolation

Enable to prevent guests from communicating with each other:

1. Navigate to Settings → Wireless Networks
2. Edit your guest SSID
3. Enable Block LAN to WLAN Multicast and Broadcast Data
4. Under Advanced, enable L2 Isolation (if available)

RADIUS Accounting

Enable RADIUS accounting for session tracking:

1. Navigate to Settings → Profiles → RADIUS
2. Create or edit a RADIUS profile
3. Configure:

Setting	Value
Name	IronWifi RADIUS
Authentication Servers
- IP Address	Primary IP from IronWifi
- Port	1812
- Shared Secret	From IronWifi
Accounting Servers
- IP Address	Primary IP from IronWifi
- Port	1813
- Shared Secret	From IronWifi
Accounting Interval	300 seconds

WPA-Enterprise Configuration

For secure 802.1X authentication without captive portal:

1. Navigate to Settings → Wireless Networks
2. Create or edit an SSID
3. Configure:

Setting	Value
Security	WPA-Enterprise
RADIUS Profile	Select IronWifi RADIUS profile
Guest Policy	Disabled

4. Click Save

Multiple Captive Portals (Multi-SSID)

Use different splash pages for different SSIDs:

1. Create multiple Captive Portals in IronWifi
2. Create a "router" splash page that redirects based on SSID:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Redirecting...</title>
  <script>
    function getUrlParam(parameter, defaultvalue) {
      var urlparameter = defaultvalue;
      if (window.location.href.indexOf(parameter) > -1) {
        urlparameter = getUrlVars()[parameter];
      }
      return urlparameter;
    }

    function getUrlVars() {
      var vars = {};
      window.location.href.replace(/[?&]+([^=&]+)=([^&]*)/gi,
        function(m, key, value) {
          vars[key] = value;
        });
      return vars;
    }

    var ssid = decodeURIComponent(getUrlParam('ssid', 'none'));

    // Configure your SSID to portal URL mappings
    var portalMap = {
      'Guest-Lobby': 'https://us-east1-r-PORTAL1.ironwifi.com/',
      'Guest-Conference': 'https://us-east1-r-PORTAL2.ironwifi.com/',
      'Guest-Cafe': 'https://us-east1-r-PORTAL3.ironwifi.com/'
    };

    var targetPortal = portalMap[ssid] || 'https://us-east1-r-DEFAULT.ironwifi.com/';
    window.location.replace(targetPortal + location.search);
  </script>
</head>
<body>
  <p>Redirecting to login page...</p>
</body>
</html>

3. Upload this as your main splash page
4. Each SSID will redirect to its designated portal

---

UniFi Cloud Key / Dream Machine

Cloud Key Setup

For UniFi Cloud Key (UCK-G2, UCK-G2-Plus):

1. Ensure Cloud Key has internet access
2. Use Cloud Key's public IP or configure port forwarding
3. Default controller URL: https://cloud_key_ip:8443

Dream Machine / Dream Router

For UDM, UDM-Pro, UDM-SE, UDR:

1. Controller is built into the device
2. Access via https://udm_ip or UniFi.ui.com
3. For external access, use UniFi.ui.com remote access or port forwarding
4. Configure port forwarding if needed:
   • External: 443 or 8443
   • Internal: 443 (UDM uses 443, not 8443)

UDM API Differences

Dream Machine products use a slightly different API. IronWifi automatically detects and adapts to UDM devices.

UniFi.ui.com (Remote Access)

If using UniFi's cloud remote access:

1. Enable Remote Access in UniFi settings
2. In IronWifi, you may need to use the Proxy option
3. Some features may require direct controller access

---

Testing and Verification

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

Test Captive Portal Flow

1. Connect a device to the guest SSID
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

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. In UniFi Controller, go to Clients
2. Find your test device
3. Verify it shows as "Authorized" after authentication

Review IronWifi Logs

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

---

Troubleshooting

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

Splash Page Not Appearing

Symptom	Cause	Solution
No redirect	Guest Policy disabled	Enable Guest Policy on SSID
Wrong page	Incorrect Custom Portal	Set Custom Portal to 107.178.250.42
HTTPS error	Secure Portal misconfigured	Enable "Use Secure Portal" and set hostname
Cached auth	Previous authorization	Clear browser cache or use incognito

Verification steps:

1. Verify Guest Policy is enabled on the SSID
2. Check Pre-Authorization Access includes 107.178.250.42
3. Confirm Authentication is set to "External Portal Server"
4. Test from a device that has never connected before

Controller Connection Errors

unifi_authentication_failed

Cause: Invalid controller credentials

Solutions:

1. Verify username and password in IronWifi settings
2. Create a dedicated admin account in UniFi:
   • Navigate to Admins → Add Admin
   • Grant "Full Admin" or "Site Admin" privileges
3. Update credentials in IronWifi Captive Portal settings
4. Avoid special characters in password that may cause encoding issues

500 Gateway Timeout / unifi_gw_connection_failed

Cause: IronWifi cannot reach your controller

Solutions:

1. Verify controller is running and accessible
2. Check public IP is correct (not private IP)
3. Configure port forwarding:
   • Router external: 8443/TCP → Controller internal: 8443/TCP
4. Check firewall allows incoming connections on port 8443
5. Try enabling Use Proxy option
6. If using DDNS, verify hostname resolves correctly

SSL Certificate Errors

Cause: Self-signed or invalid SSL certificate

Solutions:

1. Enable "Use Secure Portal" in Guest Control
2. Install a valid SSL certificate on controller:
   • Use Let's Encrypt with Certbot
   • Import certificate via UniFi settings
3. Or accept that connections will use unverified SSL

Users Not Getting Internet After Auth

Symptom	Cause	Solution
Stuck on splash	Controller authorization failed	Check controller connection
Partial access	Walled garden too restrictive	Add required domains
DNS issues	DNS not in pre-auth	Ensure DNS is allowed

Verification steps:

1. Check IronWifi Controller Status is "Connected"
2. Verify controller URL and credentials
3. Test controller accessibility from internet
4. Enable Proxy option if behind restrictive firewall

Social Login Not Working

Symptom	Cause	Solution
OAuth page won't load	Missing walled garden entries	Add provider domains
Login popup blocked	CNA browser limitation	User opens full browser
Redirect fails	Missing callback domains	Add all OAuth domains

Verification steps:

1. Add all required domains for the provider
2. Test in full browser, not CNA popup
3. Check IronWifi OAuth configuration

Client Shows Authorized But No Internet

Causes and solutions:

1. VLAN misconfiguration - Verify guest VLAN has internet route
2. Firewall rules - Check guest network firewall allows internet
3. DNS issues - Ensure DNS servers are configured
4. Double NAT - Check network topology

---

Best Practices

Security

• Create dedicated admin account for IronWifi
• Use strong, unique RADIUS shared secret
• Enable Guest Policy isolation
• Place guests on dedicated VLAN
• Set appropriate session timeouts

Performance

• Set reasonable bandwidth limits
• Enable Cloud CDN for splash page assets
• Keep splash page design lightweight
• Use 5GHz band for better performance

User Experience

• Set expiration to 8+ hours to reduce re-authentication
• Offer multiple authentication options
• Test on iOS and Android devices
• Provide clear instructions on splash page

Maintenance

• Monitor controller connection status
• Review authentication logs regularly
• Update UniFi Controller regularly
• Document your configuration

---

Quick Reference

Required Settings Summary

Setting	Location	Value
Guest Policy	SSID Settings	Enabled
Authentication	Guest Control	External Portal Server
Custom Portal	Guest Control	107.178.250.42
Pre-Auth Access	Guest Control	107.178.250.42 + providers
Controller URL	IronWifi	https://public_ip:8443

Default Ports

Service	Port	Protocol
UniFi Controller	8443	TCP/HTTPS
RADIUS Auth	1812	UDP
RADIUS Acct	1813	UDP

IronWifi Proxy IPs (for firewall whitelisting)

35.184.225.240
35.201.240.80
35.195.230.167

Related Topics

• UniFi Hotspot (v8/v9)
• UniFi Passpoint Configuration
• Captive Portals Overview
• Authentication Providers
• Walled Garden Guide