Connect TP-Link Omada to VoqadoWiFi: Controller URL & Portal Auth

Overview

This tutorial covers the complete integration between TP-Link Omada Software Controller (v5.x or later) and VoqadoWiFi's external portal authentication system. By the end, guests who join your SSID will be redirected to your VoqadoWiFi captive portal, authenticate via email, and be granted network access automatically through MAC-based authorisation.

Step 1: Find Your Controller URL

Your Omada controller URL is the base address used to reach the controller's management interface. If you're running Omada Software Controller on a server or VPS, this is typically 'https://[server-ip]:8043'. If you're using Omada Cloud-Based Controller (OC200/OC300), the URL format is different — log into the Omada app, navigate to your site, and look under Settings → Site Settings → Controller Info for the external API URL. Write this down — you'll need it in Step 7.

Step 2: Ensure the Controller Is Externally Reachable

VoqadoWiFi's servers need to reach your Omada controller to validate authentication tokens. From a device outside your local network, try opening your controller URL in a browser. If you can't reach it, you need to either: configure port forwarding on your router (port 8043 TCP), set up a static public IP or DDNS hostname (services like DuckDNS or No-IP work well), or use a reverse proxy like Nginx or Cloudflare Tunnel. Self-signed SSL certificates will cause connection errors — either install a valid certificate (Let's Encrypt is free) or enable the "Allow self-signed certificate" toggle in VoqadoWiFi's integration settings.

Step 3: Create a Dedicated Omada API Operator Account

In Omada Controller, go to Settings → Administrators. Click + Add. Set the role to Operator (not Viewer — Operator permissions are required to authorize clients). Give the account a dedicated name like 'voqado-api' and a strong auto-generated password. Do not use your personal admin credentials — if you ever rotate your password, the integration will break. Save the credentials securely.

Step 4: Enable External Portal Authentication in Omada

In your Omada Controller, navigate to your site, then go to Settings → Authentication → Portal. Click + Create Portal or edit your existing portal. Under Authentication Type, select External Portal. This tells Omada to redirect unauthenticated clients to an external URL instead of handling authentication internally.

Step 5: Set the Portal URL

In the External Portal URL field, enter your VoqadoWiFi portal URL. The format is: 'https://www.voqadowifi.com/portal/YOUR-LOCATION-SLUG'. Replace 'YOUR-LOCATION-SLUG' with the slug shown in your VoqadoWiFi dashboard under Locations. This URL is where Omada will redirect guests. Omada automatically appends query parameters to this URL: '?nasid=...&mac=...&ip=...&ap=...&ssid=...&url=...' — VoqadoWiFi parses these to identify the guest's device and network context.

Step 6: Configure HTTPS and Auth Timeout

Still in Omada's portal settings, set HTTPS Redirect to enabled — this ensures the captive portal URL loads over HTTPS, which is required for cookie-based sessions. Set Authentication Timeout to 7 days (604800 seconds). This controls how long a guest remains authorised before needing to log in again. For hospitality venues, 7 days is a good default — guests won't be re-prompted on return visits within the week.

Step 7: Enter Credentials in VoqadoWiFi

In your VoqadoWiFi dashboard, go to Settings → Integrations → Omada. Enter: your Controller URL from Step 1, your Omada operator username and password from Step 3, and select the correct site from the dropdown. Click Test Connection. A successful test confirms VoqadoWiFi can authenticate with Omada's API.

Step 8: Test the MAC Auth Flow

Connect a test device to your WiFi SSID. You should be redirected to the VoqadoWiFi portal. Complete the login form. After submission, VoqadoWiFi calls the Omada API to authorise your device's MAC address, and you should gain internet access within 2-3 seconds. If access is not granted, check the Integration Logs in VoqadoWiFi (Settings → Integrations → Logs) for error details.

Step 9: Common Errors and Fixes

"Connection refused" on test: Firewall is blocking port 8043. Open the port or use a reverse proxy on port 443. "SSL certificate error": Install a valid TLS certificate or enable the self-signed cert bypass in VoqadoWiFi settings. "Invalid credentials": Omada operator account password has been changed — update it in VoqadoWiFi settings. "Site not found": Ensure you've selected the correct site in VoqadoWiFi's integration dropdown — site names are case-sensitive. Guest redirected but not getting access: Check that the SSID in Omada has the portal enabled and is linked to the correct portal config you set up in Step 4.