TP-Link Omada Integration

Connect CaptiFi to your TP-Link Omada network. This guide covers the complete setup for Omada hardware controllers, software controllers, and Omada Cloud-Based Controllers (CBC).

Important

The External Portal URL and Pre-Auth domains must be entered exactly as shown. Incorrect values will prevent the captive portal from working.

Prerequisites

• TP-Link Omada Controller (hardware, software, or cloud-based)
• Controller firmware 5.x or later recommended
• Omada EAP access point(s) adopted and online
• Admin access to the Omada Controller
• CaptiFi account at app.captifi.io

Overview

The TP-Link Omada integration involves four steps:

1. Guest SSID — Create a dedicated guest wireless network
2. External Portal — Configure the captive portal redirect to CaptiFi
3. Walled Garden — Allow pre-authentication access to CaptiFi domains
4. Controller Connection — Link your Omada Controller to CaptiFi

---

Step 1: Create a Guest SSID

Set up a dedicated wireless network for your guests.

1.1: Create the Network

1. Open your Omada Controller (local or cloud)
2. Go to Settings → Wireless Networks
3. Click Create New Wireless Network
4. Configure:
   • SSID Name: Your guest WiFi name (e.g., "Free WiFi")
   • Security: None (open) — recommended for guest WiFi
   • SSID Broadcast: Enabled
5. Under Band, select your preferred band (2.4 GHz, 5 GHz, or both)
6. Click Save

1.2: Assign to a VLAN (Recommended)

For network isolation, assign your guest SSID to a separate VLAN:

1. Go to Settings → Wired Networks → LAN
2. Create a new network/VLAN for guest traffic
3. Return to your wireless network settings and assign the guest SSID to this VLAN

---

Step 2: Configure External Portal

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

2.1: Create a Portal

1. Go to Settings → Authentication → Portal
2. Click Create New Portal
3. Configure the following settings:

Setting	Value
Portal Name	CaptiFi Portal (or any name)
SSID	Select your guest SSID
Authentication Type	External Portal Server
Portal URL	https://app.captifi.io/portal/omada

2.2: Configure Authentication Settings

1. Under Authentication, ensure:
   • Authentication Type is set to External Portal Server
   • Portal Customisation is set to External Portal Server (not local web portal)
2. Set the Authentication Timeout to your preferred session duration

2.3: Landing Page Redirect

Under the portal configuration:

1. Set Redirect to the desired post-login behaviour:
   • To the original URL — Redirects guests to the site they originally requested
   • To a custom URL — Redirects guests to a URL of your choice (e.g., your business website)

---

Step 3: Walled Garden / Pre-Auth Domains

The Walled Garden (also called Pre-Authentication Access) allows guests to reach CaptiFi's servers before they log in. Without these entries, the splash page cannot load.

3.1: Add Pre-Auth Domains

1. In the portal configuration, find the Pre-Auth Policy or Walled Garden section
2. Enable the Walled Garden / Pre-Auth Policy
3. Add the following domains and IP addresses:

Domain / IP
site.app.captifi.io
*.captifi.io
app.captifi.io
157.230.53.133
fonts.googleapis.com
fonts.gstatic.com

TIP

Some Omada Controller versions use IP-based walled garden entries only. If your controller doesn't support domain-based entries, add the IP address 157.230.53.133 and resolve the other domains to their IPs.

3.2: Save Portal Configuration

Click Save or Apply to save your portal configuration.

---

Step 4: Connect Controller to CaptiFi

Link your Omada Controller so CaptiFi can manage guest authentication.

Option A: Omada Cloud-Based Controller

1. Log in to app.captifi.io
2. Go to Settings → Integrations
3. Select TP-Link Omada
4. Choose Cloud-Based Controller
5. Enter your Omada Cloud credentials (Omada controller ID and client credentials)
6. Click Connect
7. CaptiFi will discover your sites and access points
8. Select which site(s) to manage

Option B: On-Premise Controller (Hardware/Software)

1. Ensure your Omada Controller is remotely accessible (port forwarding may be required)
   • Default port: 8043 (HTTPS) or 8088 (HTTP)
2. Log in to app.captifi.io
3. Go to Settings → Integrations
4. Select TP-Link Omada
5. Choose On-Premise Controller
6. Enter your controller URL (e.g., https://YOUR_PUBLIC_IP:8043)
7. Enter your Omada admin username and password
8. Click Connect

Verify Port Forwarding (On-Premise Only)

If using an on-premise controller, verify remote access:

1. Find your public IP at whatismyip.com
2. Test by visiting https://YOUR_PUBLIC_IP:8043 from outside your network
3. You should see the Omada login page (you may need to accept a security warning)

---

Step 5: 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 (e.g., http://example.com)
4. Complete the login form on the splash page
5. Verify internet access after login
6. Check your CaptiFi dashboard — the guest should appear in your logs

---

Troubleshooting

Issue	Solution
Splash page not appearing	Verify the portal is enabled, the correct SSID is selected, and Authentication Type is set to External Portal Server
"Portal unreachable" error	Check that Walled Garden / Pre-Auth Policy includes site.app.captifi.io and 157.230.53.133
Blank or broken splash page	Ensure fonts.googleapis.com and fonts.gstatic.com are in the Walled Garden so page assets can load
Guest can't get online after login	Verify the portal authentication timeout hasn't expired; check VLAN/firewall rules aren't blocking post-auth traffic
Controller not connecting to CaptiFi	Check port forwarding is working for on-premise controllers (test from outside your network on port 8043)
"Invalid credentials" in CaptiFi	Verify your Omada admin username and password; ensure the account has full admin privileges
Portal only works on some APs	Ensure all EAPs are adopted, online, and broadcasting the guest SSID; re-provision APs if needed
HTTPS sites not triggering redirect	Guests may need to visit an HTTP site first (e.g., http://example.com) to trigger the portal redirect
Walled Garden not accepting domains	Some Omada firmware versions only support IP-based entries — add 157.230.53.133 as an IP entry instead

---

Multiple Sites

If you manage multiple Omada sites or locations:

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

---

Next Steps

• Customise your splash page
• Set up email campaigns

---

Need Help?

TP-Link Omada setups can vary depending on your controller type and firmware version. If you're stuck:

• Email: hello@captifi.io
• Live Chat: Available on captifi.io
• Omada Documentation: TP-Link Omada Support