Omada captive portal setup, start to finish

Pick your controller first

The portal setting is identical on all three. Where the controller lives decides the one step that differs: how VoqadoWiFi hands the guest’s token back to it.

The seven steps

1. 1
   Open the portal settings for your guest SSID

   In the Omada controller go to Settings, Authentication, Portal. Edit the portal bound to your guest SSID, or create one and bind it to that SSID. Pick the right site first if the controller has several.
2. 2
   Set the authentication type to External Portal Server

   Change it from No Authentication, Simple Password or Voucher to External Portal Server. This is what stops Omada serving its own login page.
3. 3
   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 its own parameters, and a second query string breaks the redirect.
4. 4
   Add the walled garden entries

   Add www.voqadowifi.com and voqadowifi.com to Pre-Authentication Access. Without them an unauthorized phone cannot fetch the portal, so the page never loads. Why each entry is there.
5. 5
   Give the token call a way back to your controller

   Cloud-based controller: nothing to do. OC200, OC300 or software controller: the controller must answer from the internet over HTTPS with a trusted certificate, on the port you save in the dashboard (443 when you save none). A tunnel or a reverse proxy does both. See the OC200 page or the software controller page.
6. 6
   Save the controller in the VoqadoWiFi dashboard

   Open the location and enter the Omada Controller URL, the Site ID, and the Controller ID that appears as omadacId in the redirect. Saving the Controller ID lets authorization work even if a redirect arrives without it.
7. 7
   Test on a phone that has never joined, then read Portal Health

   Join the guest SSID with mobile data off, submit the form and confirm the device reaches the internet within a few seconds. Portal Health in the dashboard shows the attempt, and the Omada error code if it failed.

What happens when a guest connects

Knowing the hand off turns troubleshooting into a checklist. The phone joins the open guest SSID and runs its own connectivity check. The access point intercepts it and redirects the phone to your portal URL with clientMac, apMac, ssidName, radioId, a one time token, the page the guest wanted as redirectUrl, and on current and cloud controllers omadacId.

The guest fills in the form. VoqadoWiFi then posts the token, the device and access point MACs, the SSID, the radio and a session length back to the controller at /<omadacId>/portal/auth. The controller checks the token and opens the firewall for that device. Codes -1 and -3 in the answer mean the device was already authorized, and the integration counts them as success.

If the token is rejected and the location has Omada OpenAPI or hotspot operator credentials on file, the integration tries those next. If everything fails, the guest still sees a result screen telling them their details were saved and how to reconnect, and the attempt lands in Portal Health with its error kind and code.

Three mistakes that break first attempts

1. A query string in the portal URL

Omada appends its own parameters. If the URL you pasted already contains a question mark and a parameter, the two collide, the portal loads with no device to authorize, the guest fills in the form, and nothing happens. Paste the URL exactly as the dashboard prints it.

2. An empty walled garden

Before authorization Omada blocks everything except Pre-Authentication Access. Without www.voqadowifi.com and voqadowifi.com on that list, the phone cannot load the page it is being sent to. The full list and the reason for each line are on the walled garden page.

3. A controller the internet cannot reach

On an OC200 or a software controller, the token goes back to the controller address you saved in the dashboard, over HTTPS on the port that address names (443 when it names none), with the certificate checked. A LAN address, a missing port or a self signed certificate each stop it. The cloud-based controller avoids this entirely.

What Omada does on its own, and what it does not

If all you need is a terms page and a password, Omada already does that and you should not add a second system. The external portal earns its place only if you intend to use the list afterwards.

Before you start

• Keep the guest SSID open. A portal behind a WPA password is a door behind a door.
• Leave guest isolation on, and put the guest SSID on its own VLAN where your switching allows it.
• Change the portal outside your busiest hour. Devices on that SSID drop and reconnect.
• Keep one phone that has never joined the network for testing. A phone that already has a session skips the portal.

Omada questions

When something is not working

• Portal loads but the WiFi never unlocks
• Omada authorization error codes, explained
• Captive portal not showing on iPhone
• Guests have to log in every day
• All troubleshooting guides

Deeper reading

The longer Omada articles from the blog. Where an article and this page disagree, this page is the one checked against the current integration.

• How the captive portal mini browser behaves. Why the login window is not Safari or Chrome, and what that changes.
• Guest VLAN segmentation. Keep authorized guests off your point of sale and office network.
• Guest bandwidth management. Rate limits that guests never notice.
• Access point placement for venues
• WiFi 6 vs WiFi 7 for venues

Keep reading

Get your Omada portal URL free Create the free account, add your venue, and the dashboard prints the exact URL to paste into the controller. One location and 500 guest logins a month, no card. Create your free account