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 the paid Omada Cloud-Based Controller (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.

Omada Cloud Essentials is not supported

The free Omada Cloud Essentials tier (controller addresses like xxx-omada-essential-device.tplinkcloud.com) has no external portal API, so CaptiFi cannot connect to it. If your access points are managed by Cloud Essentials, move them to an OC200/OC300, the free self-hosted software controller, or the paid Cloud-Based Controller. A CaptiFi Plug and Play device also works with no controller at all. Email support@captifi.io if you are not sure which you have.

WiFi 7 access points or Starlink internet?

Running the BE9300 WiFi 7 ceiling mount APs (EAP772/EAP773), or a venue on Starlink? See the dedicated Omada WiFi 7 + Starlink guide — it covers controller version requirements, 6 GHz guest SSID limitations, and how to work around Starlink's CGNAT.

Prerequisites

• TP-Link Omada Controller: hardware (OC200/OC300), self-hosted software, or the paid Cloud-Based Controller (the free Cloud Essentials tier is not supported)
• Controller firmware 5.x or later recommended (v5.15+ required for WiFi 7 EAPs such as the EAP772/EAP773)
• Omada EAP access point(s) adopted and online
• Admin access to the Omada Controller
• CaptiFi account at my.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/guest/omada?site_id=YOUR_SITE_ID

Your site ID

Replace YOUR_SITE_ID with your CaptiFi site ID — you'll find it in your CaptiFi dashboard, or ask support@captifi.io. This entry URL accepts the redirect parameters from all Omada controller versions (v4 and v5+) automatically.

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
app.captifi.io
*.captifi.io
46.62.168.7
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 46.62.168.7.

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.

Create an Operator Account in Omada

CaptiFi authorises guests through Omada's hotspot operator API, so it needs a dedicated operator account (not your main admin login):

1. In your Omada Controller, go to Settings → Cloud Access / Operators (location varies slightly by version — look for Hotspot Manager → Operators on some firmwares)
2. Create a new operator account (e.g. username captifi) with a strong password

Connect in CaptiFi

1. Ensure your Omada Controller is reachable from the internet (port forwarding may be required)
   • Default port: 8043 (software controller) or 443 (OC200/OC300 hardware controller)
2. Log in to my.captifi.io
3. Go to My Locations → Add location (or choose your hardware during onboarding) and select TP-Link Omada
4. Enter:
   • Controller URL: your controller's own address including port (for example https://YOUR-CONTROLLER-IP:8043 or your controller's domain). On the paid Cloud-Based Controller, use the controller URL from your Omada cloud account. Do not paste omada:// links from the Omada app: they are not controller addresses
   • Controller ID: the long ID segment from your Omada controller's URL
   • Operator username and Operator password — the account you just created
5. Click Connect — CaptiFi tests the login and confirms the link

Verify Port Forwarding

If your controller is on-premise, 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 app.captifi.io and 46.62.168.7
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 the operator username and password, and double-check the Controller ID copied from your Omada URL
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 46.62.168.7 as an IP entry instead

---

Multiple Sites

If you manage multiple Omada sites or locations:

• Each location can have its own splash page design in CaptiFi
• Manage per-location settings in My Locations on your CaptiFi dashboard (each additional CaptiFi location beyond the one included in your plan is £25/month)

---

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