UniFi Integration

Connect CaptiFi to your Ubiquiti UniFi network. This guide covers the complete setup for UniFi Dream Machine (UDM), Cloud Key, and self-hosted controllers.

Important

The portal server IP and domain must be entered exactly as shown. Incorrect values will prevent the captive portal from working.

Prerequisites

• UniFi controller (UDM, UDM Pro, Cloud Key, or self-hosted)
• Controller firmware 6.x or later
• Admin access to the UniFi controller
• CaptiFi account at app.captifi.io

Overview

The UniFi integration involves three steps:

1. Port Forwarding — Make your UniFi controller remotely accessible
2. Controller Connection — Link your controller to CaptiFi
3. Captive Portal Configuration — Set up the external portal redirect

---

Step 1: Port Forwarding

CaptiFi needs remote access to your UniFi controller to manage guest networks and splash pages.

UDM / UDM Pro / UDM SE

1. Open the UniFi OS console
2. Go to Settings → Firewall & Security → Port Forwarding
3. Create a new rule:
   • Name: CaptiFi Access
   • From: Any
   • Port: 443
   • Forward IP: Your UDM IP (usually 192.168.1.1)
   • Forward Port: 443
   • Protocol: TCP
4. Save

Cloud Key / Cloud Key Gen2

1. Log in to your router/gateway admin panel
2. Find Port Forwarding settings
3. Create a new rule:
   • External Port: 8443
   • Internal IP: Your Cloud Key's IP address
   • Internal Port: 8443
   • Protocol: TCP
4. Save

Self-Hosted Controller

Ensure port 8443 (default) is open and accessible from the internet on your server/VM.

Verify Port Forwarding

After setting up, verify it works:

1. Find your public IP at whatismyip.com
2. Test by visiting https://YOUR_PUBLIC_IP:443 (UDM) or https://YOUR_PUBLIC_IP:8443 (Cloud Key)
3. You should see the UniFi login page (you may need to accept a security warning)

---

Step 2: Connect Controller to CaptiFi

During the CaptiFi onboarding (or from your dashboard):

1. Log in to app.captifi.io
2. If onboarding: select UniFi as your device type
3. Choose your controller type:
   • Self-Hosted / Cloud Key — Enter your controller URL (e.g., https://YOUR_PUBLIC_IP:8443)
   • UniFi Cloud API — Connect via Ubiquiti cloud account
4. Enter your UniFi admin username and password
5. Click Connect
6. CaptiFi will discover your sites and access points
7. Select which site(s) to manage
8. Import your sites

---

Step 3: Configure Captive Portal

This is the most critical step. You must configure your UniFi controller to redirect WiFi guests to CaptiFi's external portal.

3.1: Create or Edit a Guest WiFi Network

1. In your UniFi controller, go to Settings → WiFi
2. Either create a new network or edit your existing guest network
3. Set:
   • Name (SSID): Your guest WiFi name (e.g., "Free WiFi")
   • Security: Open (no password) — recommended for guest WiFi
   • Network: Guest network

3.2: Enable Hotspot Portal

1. Go to Settings → WiFi → Select your guest network
2. Scroll to Hotspot Portal and toggle it ON
3. Under Authentication, select External Portal Server

3.3: Configure External Portal Server

Enter these values exactly:

Setting	Value
IPv4 Address	157.230.53.133
Domain	site.app.captifi.io

3.4: Configure Pre-Authorization Access

Under Pre-Authorization Access (or Walled Garden), add:

Domain
site.app.captifi.io
*.captifi.io
app.captifi.io
fonts.googleapis.com
fonts.gstatic.com

3.5: Landing Page Settings

Under the Landing Page section, ensure ALL of these options are checked/enabled:

• ✅ Show Landing Page
• ✅ HTTPS Redirection Support
• ✅ Encrypted URL
• ✅ Secure Portal
• ✅ Domain — set to site.app.captifi.io

3.6: Apply Settings

Click Apply or Save to apply the configuration.

---

Step 4: Test

1. Connect a device (phone or laptop) to your guest WiFi
2. The CaptiFi splash page should appear automatically
3. If on mobile, you may need to open a browser and visit any HTTP site
4. Complete the login form
5. Check your CaptiFi dashboard — the guest should appear in your logs

---

Troubleshooting

Issue	Solution
Splash page not appearing	Verify Hotspot Portal is enabled and External Portal Server IP is exactly 157.230.53.133
"Portal unreachable" error	Check Pre-Authorization Access includes site.app.captifi.io
Guest can't get online after login	Verify the domain is set to site.app.captifi.io in Landing Page settings
Controller not connecting	Check port forwarding is working (test from outside your network)
"Invalid credentials"	Verify UniFi admin username and password in CaptiFi settings
Sites not importing	Ensure your UniFi admin account has access to the site
HTTPS redirect issues	Enable "HTTPS Redirection Support" and "Secure Portal" in Landing Page settings

Multiple Sites

If you have multiple UniFi sites:

• Each site can have its own splash page design
• Sites are automatically discovered when you connect your controller
• Manage per-site settings in Splash Pages on your CaptiFi dashboard

Need Help?

UniFi setups can vary depending on your hardware and firmware version. If you're stuck:

• Email: hello@captifi.io
• Live Chat: Available on captifi.io
• Original HTML Guide: Available in your CaptiFi portal under Help