Appearance
The redirect and the login config
The controller sends the guest to Kiwire with a handful of parameters; the login config tells Kiwire what the vendor calls them.
This is the HTTP-redirect half of Connecting a controller; RADIUS is covered there and per vendor on the vendor reference.
The redirect URL
Every controller's external captive portal / splash page setting points at the same route:
https://{host}/login/{slug}{host} is your Kiwire hostname. {slug} is the slug of an active login config — for example /login/mikrotik, /login/tplink, /login/ubnt-console. Your vendor's setup guide names the right one. The route accepts any HTTP method, so it does not matter whether the vendor redirects with a GET or posts a form. You do not write a query string yourself: the controller appends its own parameters, using its own names, and that is the whole point of the login config.
When a request lands on /login/{slug}, Kiwire looks up the config by slug (cached, so the lookup is free after the first hit), reads each Kiwire parameter from whichever request key the config names, starts a fresh portal session and sends the browser on to /captive-portal/init, where the tenant, zone and journey are resolved. If a Controller Test capture window is open, the raw request is recorded before any of that — including requests that are about to 404.
What the controller sends
Three things have to arrive for the handshake to work at all:
- The guest's MAC. Init rejects the request with
invalid_mac(HTTP 400) unless the value, with:,-and.stripped, is exactly 12 hex digits. Kiwire lowercases it and normalises-to:. - The controller ID. This is matched against the Identity of a registered Device Controller to find the tenant. The match ignores upper/lower case but nothing else —
aa:bb:…,aa-bb-…andaabb…are three different values. RADIUS is matched separately, by the NAS-Identifier; if the controller sends a different value there, that needs its own record — see Identity and Virtual NAS. Missing →NO_CONTROLLER_ID; present but not registered in any tenant →NAS_NOT_CONFIGURED. Both are shown on the portal error page. - The login URL — for vendors whose scheme has Kiwire post the credentials back to the controller after a successful login (MikroTik's
link-login, ChilliSpot'suamip, and most on-premises controllers). Without it the guest sees a login page that can never grant access.
Everything else (client IP, destination, VLAN, SSID, controller zone, error) is optional. An unmapped or unsent parameter simply resolves to empty; zone matching then ignores that attribute.
The login config, field by field
A login config is one row on the platform's controller redirection table, which Synchroweb maintains — if your vendor is not listed, Synchroweb adds it. The table is not editable from a tenant's admin panel, but its fields are what an installer needs to know. Each config has a slug (letters, digits, - and _, up to 120 characters — the {slug} in the URL), an optional cosmetic vendor label, a status, and the parameter map. In the map, each Kiwire parameter holds the name of the request key the controller sends it as.
| Kiwire parameter | What it is used for | Typical vendor name(s) in the seeded configs |
|---|---|---|
mac | Guest device MAC — session identity, auto-login, device history. Required. | mac, client_mac, usermac, user-mac, station_mac, clientMac, id (UniFi), MA (Nomadix) |
ip | Guest device IP — IP-range zone rules, firewall policy, NAS submit. | ip, client_ip, userip, user-ip, uip, wlanuserip, CLIENT_IP, SIP (Nomadix) |
destination | URL the guest originally asked for; kept for the post-login redirect. | link-orig (MikroTik), url, redirect, continue_url, original_url, redirect-url, userurl, originUrl |
controller_ip | Controller/NAS address as it reports itself; part of the NAS submit for some vendors. | nasip, switchip, apip, server_ip, ap-ip, acip, hostname (TP-Link) |
login_url | Controller's own login endpoint that Kiwire posts back to after authentication. Any ?query on the value is stripped. Required for post-back vendors. | link-login (MikroTik), switch_url (Cisco), login_url, uamip, nbiIP (Ruckus vSZ/SCG), post / grant_url (Forti), target (TP-Link) |
controller_id | Controller identity; must equal a Device Controller's Identity. Resolves the tenant and drives NAS-ID zone rules and licence device limits. Required. | nasid, ap_mac, apmac, apMac, ap, ap-mac, wlan (Cisco WLC — the SSID name), NI (Nomadix), device_name (Peplink), mac (Ruckus — the AP's MAC) |
vlan | Guest VLAN, for VLAN zone rules. | vlan, vid (TP-Link), PORT (Nomadix) |
ssid | SSID the guest joined, for SSID zone rules. | ssid, essid (Aruba), wlan (Cisco/Allied Telesis), ssidName, ssid_name, ga_ssid |
zone | A zone name the controller itself reports, for controller-zone (dzone) rules. | zone, zoneName (Ruckus vSZ/SCG) |
error | An error flag from the controller. When non-empty, init skips auto-login and goes straight to the page flow. | error (MikroTik, Mist, Ruijie, Allied Telesis) |
The slug itself is also kept, as the controller type, and decides which vendor handoff Kiwire uses when it submits the login to the NAS.
Whether an SSID, VLAN, NAS ID, IP or controller-zone value actually lands the guest in a zone depends on the tenant's Zones Mapping rules: rules are tried highest priority first, and a rule matches when every attribute it sets equals the value the redirect supplied (case-insensitive; IP by range). A rule with no attributes set is a catch-all.
Custom attributes
The form's Custom Attributes box takes a JSON object of extra mappings, {"kiwire_name": "request_key"}. They are stored in the same parameter map as the standard fields (a custom key with a standard name loses to the standard field) and, on each redirect, every custom key is read from the request and kept in the portal session under extra.
The Kiwire-side name matters: the post-login NAS handoff looks up specific extra keys for vendors whose login form needs a token the controller handed out in the redirect — magic (FortiAP), qv (Motorola, Cambium), challenge and shared_secret (ChilliSpot UAM), proxy (Ruckus AP), site_id (UniFi), and for TP-Link Omada urlscheme, login_port and radio_id. The shipped tplink config is the only one that maps any of them (scheme, targetPort, radioId). The configs are maintained by Synchroweb: if Controller Test shows your controller sending such a value and the login is not completing, contact Synchroweb rather than changing the controller.
A worked example: MikroTik
The seeded mikrotik config maps mac → mac, ip → ip, destination → link-orig, login_url → link-login, controller_id → nasid, and vlan, ssid, zone, error to keys of the same name. A hotspot redirect therefore looks like:
https://portal.example.com/login/mikrotik
?mac=00:11:22:33:44:55
&ip=192.168.88.10
&link-login=https%3A%2F%2F192.168.88.1%2Flogin%3Fdst%3Dhttp%253A%252F%252Fexample.com
&link-orig=http%3A%2F%2Fexample.com
&nasid=hotel-lobby-01Kiwire reads the MAC and IP directly, keeps link-orig as the destination, and stores link-login with its ?dst=… query stripped, so the post-back after login goes to the clean https://192.168.88.1/login. nasid has to be a registered controller's Identity — hotel-lobby-01 here — or init stops at NAS_NOT_CONFIGURED. What to put on the router so it sends nasid and a link-login at all is in the MikroTik setup guide.
One config per vendor, shared by every tenant
Login configs are shared by the whole platform, not kept per tenant. One mikrotik row serves every MikroTik hotspot on every tenant; the tenant is worked out per request from controller_id, never from the slug. A new config is only needed when a vendor or firmware names its parameters differently (which is why Ruckus has ruckus_ap, ruckus_vsz and ruckus_scg).
Kiwire ships 38 configs (not every one completes a guest login today — your vendor's setup guide says which to use): mikrotik, cmcc, cisco_wlc, nomadix, nomadix_xml, meraki, fortios, fortiap, fortilan, ruckus_ap, ruckus_vsz, ruckus_scg, motorola, xirrus, chillispot, aruba, aruba_os, aruba-mobility, engenius, cambium, huawei, huawei-nce, huawei-cloud-ugw, huawei-wlc, sundray, ubnt, ubnt-console, sonicwall, pfsense, mist, ruijie-reyee, allied-telesis, h3c, h3c-cloud, tplink, peplink, zyxelap and a generic other that maps only zone. Saving a config clears its cache immediately, so an edit is live on the next redirect. Renaming a slug moves the URL: controllers still pointed at the old one start getting 404s.
When the redirect lands on the wrong page
- 404 "not found" page straight from
/login/…— the slug has no config, or the config isinactive. Nothing is read from the request in that case. - Portal error page,
NO_CONTROLLER_IDorNAS_NOT_CONFIGURED—controller_idis not mapped, not sent, or not a registered Identity. Check the mapping first, then the Device Controller record. invalid_mac— themacmapping points at a key that is empty or not a MAC.- Guest gets the tenant's default page instead of the expected journey — no zone rule matched (the log says
zone: nozone). Kiwire then falls back to the template marked as default; if there is no published default either, the guest seesNO_PAGE_ALLOCATEDwith the resolved zone/journey/default-page chain printed on the error page. Compare the SSID/VLAN/NAS-ID the redirect carried against the zone's rules.
In every case the fastest way to see what the controller really sends is Portals › Troubleshoot › Controller Test: open a capture window, trigger the redirect from a test device, and read the raw parameter list and the per-field checklist (mac, ip, nasid, login_url critical; ssid, vlan, zone advisory). The capture shows hits from controllers already registered in your tenant. For a controller that isn't registered yet, or whose identity doesn't match, use the page's Test URL (it carries ?kw_ct=<token>) as the redirect so the hit is pinned to your window even when nothing else on it resolves.