TP-Link Omada, self hosted

Omada Software Controller captive portal setup

Name: VoqadoWiFi
Availability: InStock

The software controller is the OC200 as an application on your own PC, NAS or server. Where you run it decides whether the portal works on the first try: on a back office PC it needs the same inbound path as a box, on a VPS it already has one.

Print my Omada settings All Omada controllers

How do I use an external captive portal with the Omada Software Controller?

In the software controller open Settings, Authentication, Portal, set the guest SSID’s portal to External Portal Server and paste https://www.voqadowifi.com/portal/your-venue-slug. Allow www.voqadowifi.com and voqadowifi.com before authentication, then make the controller answer on public HTTPS port 443 with a trusted certificate, which a VPS behind a reverse proxy does naturally.

At a glance

Where it runs: Your PC, NAS or a VPS
Usual management port: 8043 in the browser
Port the token call uses: 443, with certificate checking
Portal URL: https://www.voqadowifi.com/portal/your-venue-slug
Multi venue: One controller, one Omada site per venue
Path the token goes to: /<omadacId>/portal/auth when Omada sends omadacId

Checked against the VoqadoWiFi integration code on 7 October 2026. Controller menu labels move between firmware releases; the setting names above are the ones the setup wizard prints.

Step by step

Pick where the controller lives
A spare PC in the office works for a pilot. For anything you depend on, a small VPS is the stronger choice: it is reachable from the internet by design, and one controller can hold a site for every venue.
Put HTTPS on port 443 in front of it
The software controller usually answers on 8043. The authorization call from VoqadoWiFi connects on 443 and checks the certificate, so put a reverse proxy with a free automated certificate on 443 that forwards to the controller.
Open the portal settings for the venue’s site
Choose the site from the site selector, then Settings, Authentication, Portal. Edit or create the portal bound to the guest SSID and choose External Portal Server.
Paste the portal URL exactly as the dashboard prints it
Enter https://www.voqadowifi.com/portal/your-venue-slug with no trailing slash and no question mark of your own. Omada appends clientMac, apMac, ssidName, radioId and a one time token to the URL, and a second query string breaks that hand off.
Allow the portal domain before authentication
Add www.voqadowifi.com and voqadowifi.com to Pre-Authentication Access on the same portal. The full list, with the reason for each line, is on the walled garden page.
Save the controller in the dashboard
Enter the public https:// hostname as the Omada Controller URL with no port, the Site ID, and the Controller ID shown as omadacId in a redirect URL. Saving the Controller ID lets authorization work even when a redirect arrives without it.
Test one venue end to end
Join the guest SSID on a phone that has never connected, submit the form and confirm the device gets online. Check Portal Health for the matching attempt before you roll the same portal out to the next site.

What breaks on this controller

Testing the controller URL with its management port

An address such as https://controller.example.com:8043 opens the controller in your browser, so it looks correct. The token call ignores that port and connects on 443. If nothing answers there, Portal Health shows a network failure.

Redirects that arrive without omadacId

Current controllers include omadacId in the redirect, and the token goes to /<omadacId>/portal/auth on your host. If a redirect arrives without it, the integration falls back to the site based path or plain /portal/auth. Saving the Controller ID in the dashboard removes the guesswork.

The controller PC goes to sleep

A controller on a desktop that sleeps or restarts for updates takes guest authorization with it. Guests still see the portal, because the access points redirect on their own, and then never get online.

One site for several venues

Put each venue in its own Omada site. Portal settings, SSIDs and the Site ID VoqadoWiFi stores are per site, and sharing one site mixes guests across venues.

The VPS pattern for groups

Run one software controller on a VPS, create one Omada site per venue, and adopt each venue’s access points to it over the internet. Every VoqadoWiFi location then points at the same controller hostname with its own Site ID.

The reachability problem disappears, because the controller is on the internet already. What you take on is a server: operating system updates, controller updates, backups copied off the machine, and a test login per venue after every controller upgrade.

Questions

Which version of the software controller do I need?

A current release. The integration builds the token path from the omadacId that current controllers include in the redirect, and falls back to site based and plain paths for redirects without it.

Can I keep the controller on 8043?

Keep it on 8043 internally if you like, but put HTTPS on port 443 in front of it. The authorization call connects on 443.

Do I need to open the controller to the whole internet?

It must answer the authorization call from the internet. A tunnel or a reverse proxy limited to the portal path keeps the rest of the controller private; on a VPS, restrict the management interface to your own addresses.

Is the software controller free?

TP-Link publishes it without charge. VoqadoWiFi’s Starter plan is also free: one location and 25 guest logins a month, no card.

Deeper reading

Longer articles from the blog that cover this controller. Where an article and this page disagree, this page is the one checked against the current integration.

Omada cloud vs local controller. When the software controller on a VPS beats a box per venue.
Running one controller on a VPS. Written for UniFi; the sizing, backup and update habits carry over.
Guest bandwidth management

Keep reading

Omada setup hub OC200 and OC300 setup Omada Cloud-Based Controller setup Portal loads but the WiFi never unlocks

Sources: lib/omada/api.ts (buildAuthUrl and the token call) and the setup wizard, read on the date above. TP-Link and Omada are trademarks of TP-Link Technologies. VoqadoWiFi is not affiliated with or endorsed by either vendor.

Run your Omada portal free

One location and 25 guest logins a month on the Starter plan, no card. The dashboard prints the finished portal URL for this controller.