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, UDM SE, Cloud Key, or self-hosted)
• Controller firmware 6.x or later (API Key method requires 10.2+)
• Admin access to the UniFi controller
• CaptiFi account at app.captifi.io

Overview

The UniFi integration involves these steps:

1. Controller Access — Make your UniFi controller accessible to CaptiFi (firewall rule or API key)
2. Controller Connection — Link your controller to CaptiFi
3. Captive Portal Configuration — Set up the external portal redirect
4. Test — Verify guests are redirected to your splash page

---

Step 1: Controller Access

CaptiFi needs to communicate with your UniFi controller to manage guest networks and authorise devices. Choose the method that matches your setup.

Recommended: API Key Method (Firmware 10.2+)

If your controller supports API keys, you can skip firewall rules and port forwarding entirely. The API key method is more secure and simpler to set up. Jump to Step 2 and choose Connect via API Key.

UDM / UDM Pro / UDM SE — Firewall Rule

On a UDM, the UniFi controller runs on the gateway itself. You need a firewall rule that allows CaptiFi's servers to reach the gateway on specific ports. This is a Firewall Rule (not Port Forwarding), because the traffic is destined for the gateway, not a device behind it.

1a: Create a Port Group

1. Open the UniFi OS console
2. Go to Settings → Firewall & Security → Firewall Rules
3. Go to Port Groups (or Groups → Port Groups depending on firmware)
4. Create a new port group:
   • Name: Captifi
   • Ports: 80, 443

1b: Create the Firewall Rule

1. Still in Settings → Firewall & Security → Firewall Rules
2. Click Create New Rule and configure:

Setting	Value
Name	CaptiFi Access
Action	Allow
Source Zone	External
Source Type	Any
Source Port	Any
Destination Zone	Gateway
Destination Type	Any
Destination Port	Port Group → Captifi
IP Version	IPv4
Protocol	All
Auto Allow Return Traffic	Enabled

3. Save the rule

What does this rule do?

This creates a WAN-to-Gateway allow rule scoped by port group. It permits any device on the internet to reach your gateway on ports 80 and 443 only. The Gateway destination zone means traffic targets the router itself (where the UniFi controller runs), not devices on your LAN. Return traffic is automatically allowed via the stateful Auto Allow Return Traffic setting.

IPv6 Note

This rule applies to IPv4 only. If your network has IPv6 enabled, you may need a separate rule for IPv6 traffic, or ensure IPv6 is not in use for the controller.

Cloud Key / Cloud Key Gen2

The Cloud Key is a separate device on your LAN, so you need traditional Port Forwarding on your router to make it accessible from the internet.

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 Controller Access

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)

TIP

Test from outside your network (e.g., from your mobile phone on 4G/5G, not WiFi) to confirm the rule is working correctly.

---

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 connection method:

Option A: API Key (Recommended — firmware 10.2+)

This is the simplest and most secure method. No port forwarding or firewall rules required.

1. In your UniFi controller, go to Settings → API (or OS Settings → API)
2. Create a new API key
3. Copy the API key
4. In CaptiFi, select Connect via API Key
5. Enter your controller URL and API key
6. Click Connect — CaptiFi will discover your sites automatically

Option B: Username & Password (Legacy)

This method requires a local account on your UniFi controller. Your normal Ubiquiti SSO (cloud) login will not work — CaptiFi connects directly to the controller's local API, which only accepts local credentials.

Create a Local Admin Account

Required Step

If you only have a Ubiquiti SSO login (the one you use at ui.com), you must create a local account first. Without it, CaptiFi cannot authenticate with your controller and you will see "Invalid credentials" errors.

On UniFi OS (UDM, UDM Pro, UDM SE):

1. Log in to your UniFi OS console (e.g., https://192.168.1.1)
2. Go to OS Settings (the gear icon in the top-left, outside of the Network app)
3. Select Admins & Users
4. Click Add Admin
5. Choose Local Access Only (not "Ubiquiti Account")
6. Fill in the details:
   • Username: Choose a username (e.g., captifi)
   • Password: Choose a strong password
   • Role: Administrator (full access is required for guest authorisation)
7. Click Add

On Cloud Key / Self-Hosted Controller:

1. Open the UniFi Network controller web interface
2. Go to Settings → Admins
3. Click Add New Admin
4. Select Local admin only (do NOT invite via Ubiquiti account)
5. Enter a username and password
6. Set Role to Administrator
7. Click Create

Best Practice

Create a dedicated account specifically for CaptiFi (e.g., username captifi). This makes it easy to identify CaptiFi's API access in your controller logs and allows you to revoke access without affecting your own admin login.

Connect to CaptiFi

1. In CaptiFi, select Self-Hosted / Cloud Key
2. Enter your controller URL (e.g., https://YOUR_PUBLIC_IP:8443)
3. Enter the local account username and password you just created
4. Click Connect

Option C: UniFi Cloud API

1. Select UniFi Cloud API
2. Connect via your Ubiquiti cloud account

After connecting:

1. CaptiFi will discover your sites and access points
2. Select which site(s) to manage
3. 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 your firewall rule or port forwarding is working (test from outside your network)
"Invalid credentials"	You must use a local account, not your Ubiquiti SSO (cloud) login. See Create a Local Admin Account above
API key not working	Ensure your controller firmware is 10.2+ and the API key has not expired
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
Firewall rule not working on UDM	Ensure Destination Zone is Gateway (not LAN), and the port group contains 80 and 443

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