TP-Link Omada

How to connect TP-Link Omada EAP access points, managed by an Omada software controller, hardware controller (OC series) or Omada cloud controller, to Kiwire.

Device type in Kiwire	TP Link
Redirect URL	https://<kiwire-host>/login/tplink (Omada's external web portal URL)
RADIUS	auth 1812 / acct 1813 (UDP)
Identity must equal	Each AP's MAC as Omada sends it in apMac (capitals with dashes, for example AC-84-C6-12-34-56), plus one record for the portal's NAS ID
Disconnect / live changes (CoA)	Standard RADIUS Disconnect / CoA to the record's IP Address (see Limits)
Data caps	Time limits only (Session-Timeout)

Read Controller identity and Virtual NAS once before your first installation.

How a login works

1. A guest joins the SSID. Omada sends their browser to the external portal, Kiwire, and adds its own parameters: the guest's MAC and IP (clientMac, clientIp), the AP's MAC (apMac), ssidName, radioId, vid, the original page (originUrl), and where to send the login back to: target, targetPort and scheme.
2. The guest logs in on the Kiwire portal.
3. Kiwire sends the guest's browser to <scheme>://<target>:<targetPort>/portal/radius/browserauth with the username, password and the client and AP details.
4. Omada checks those credentials with Kiwire over RADIUS, then lets the guest on.

Steps 2 and 4 are the controller's side of the portal, step 5 is its RADIUS side. When the page loads but the login never completes, the break is almost always at step 4 (the login address) or step 5 (the Identity or the shared secret).

The address, port and http/https for step 3 all come from Omada's own redirect (target, targetPort, scheme). You don't enter them anywhere in Kiwire, and the IP Address on the Kiwire record is not used for them.

Which records you need

Omada uses two different values:

• Portal: the redirect carries the AP's MAC in apMac, in capitals with dashes (AC-84-C6-12-34-56). Each AP that broadcasts the guest SSID needs a record with exactly that Identity.
• RADIUS: Omada sends the NAS ID you set on the portal as NAS-Identifier. Set it to one fixed text for the site, for example acme-omada-kl, and add one record with that Identity.

So a site with 8 APs needs 9 records. All of them need the same Shared Secret Key, and all count toward your licence. The NAS ID record works like a Virtual NAS.

If you leave the NAS ID empty, check what arrives before relying on it: Kiwire then falls back to the AP MAC from Called-Station-Id, written with colons (AC:84:C6:12:34:56), which is a different Identity from the dash form in apMac.

Before you start

From Kiwire:

• The RADIUS server address shown in the Setup Guide checklist (Before you add your controller › RADIUS Authentication & Accounting). Below it is written <radius-server-ip>.
• Your <kiwire-host>: the host name of your portal. Portals › Troubleshoot › Controller Test shows it in the Test URL field.
• A <shared-secret> of 64 characters or fewer.
• A NAS ID for the site: at least 4 characters and unique across the whole Kiwire platform.

From Omada:

• Admin access to the Omada controller, and the site that has the guest SSID.
• The list of AP MAC addresses (Devices).
• Omada Controller 5.x or later is assumed below. Older versions have the same settings under different menus.

On the controller

Menu names and commands vary between firmware versions; the values are what matter.

1. RADIUS profile. Settings › Profiles › RADIUS Profile (older versions: Settings › Authentication › RADIUS) → Create New RADIUS Profile:
   • Authentication Server IP: <radius-server-ip>, Port: 1812, Password: <shared-secret>
   • RADIUS Accounting: enabled. Accounting Server IP: <radius-server-ip>, Port: 1813, Password: <shared-secret>
2. Portal. Settings › Authentication › Portal → Create New Portal:
   • SSID & Network: your guest SSID.
   • Authentication Type: External RADIUS Server.
   • RADIUS Profile: the profile from step 1.
   • NAS ID: the fixed site text you chose (see "Which records you need").
   • Portal Customization: External Web Portal, URL https://<kiwire-host>/login/tplink
   • Don't add a query string: Omada appends its own parameters, and Kiwire's login config already reads them.
3. Pre-authentication access. In the same portal, Access Control › Pre-Authentication Access (enable it): add <kiwire-host>, fonts.googleapis.com and fonts.gstatic.com as URL entries, plus anything else your portal loads (see Walled garden and redirect). If your version only accepts IP ranges, use the addresses those names resolve to.
4. Let guests reach the controller's portal port. The hand-back in step 3 of "How a login works" goes from the guest's browser to target:targetPort (for a local controller, the controller's address and its portal port, 8843 for HTTPS by default). Make sure the guest network can reach it.
5. Apply.

In Kiwire

1. Admin › System › Device Controller: add

   • one record per AP: Vendor TP Link, Identity = the AP's MAC exactly as in apMac (capitals with dashes), Shared Secret Key <shared-secret>;
   • one record for the NAS ID: Vendor TP Link, Identity = the NAS ID from the portal, the same Shared Secret Key.

   For many APs, use the CSV import on the same page (columns unique_id, vendor, shared_secret; vendor tplink).

2. Check the redirect parameters. The TP Link login config is maintained by Synchroweb. It reads clientMac, clientIp, originUrl, target, apMac, vid, ssidName, radioId, scheme and targetPort. See The redirect and the login config.

3. Zones and journeys. Under Portals › Captive Portal › Zones Mapping, zone rules on SSID (ssidName), VLAN (vid) or NAS ID (the AP's MAC) select a zone. See Controllers and zones and Designers and journeys.

Test it

1. Portals › Troubleshoot › Controller Test → Start Capture, then connect a phone to the guest SSID. Check that clientMac, target, targetPort, scheme and apMac arrive, and that the controller ID (the AP's MAC) is registered to your organisation. Compare the MAC's format with your Identity if it is not.
   • target must be a bare address or host name. If it already starts with http:// or https://, the login will not complete: contact Synchroweb support.
2. Log in as a guest. If the portal accepts the login but the guest stays offline, check that the guest network can reach target:targetPort, then the RADIUS profile, the secret and the NAS ID record.
3. Reporting › Login › Active Session: the session should appear once accounting arrives.

Limits to know

• Wireless guests on EAPs only. Kiwire's TP Link login config identifies the site by the AP's MAC (apMac). A portal that runs on an Omada gateway for wired clients sends gatewayMac instead of apMac and is not covered by this setup. Contact Synchroweb before deploying one.
• Add records before the device goes live. Kiwire accepts a new record straight away. If the device already sent RADIUS requests before its record existed, they can keep failing for up to an hour. See Controller identity and Virtual NAS.
• One secret for everything behind one address. Every record for the site must share the Shared Secret Key. If your RADIUS requests come from an Omada cloud controller, other organisations' requests may come from the same addresses: ask Synchroweb support which secret to use before you start.
• Disconnects and live changes. Kiwire sends standard RADIUS disconnect and CoA requests to the record's IP Address : COA Port. Omada's documentation for external RADIUS portals does not list support for them, so plan for profile changes to apply from the guest's next login.
• No data caps. Kiwire has no Omada data attribute. Session length comes from Session-Timeout.
• AP MAC format. AC-84-C6-12-34-56, ac:84:c6:12:34:56 and ac84c6123456 are different Identities. Copy the MAC from Controller Test.

Vendor reference

• API and Code Sample for RADIUS Server with External Web Portal (Omada Controller 4.1.5 or above): portal settings, redirect parameters, the /portal/radius/browserauth hand-back.