Kiwire docs

Appearance

Connecting a controller ​

Written for whoever is in the controller's admin console. What every vendor needs, then the setup guide for your vendor. For the order to do things in, follow Set up a controller, step by step.

What Kiwire needs from every controller ​

A "controller" here is whatever the guest's device actually talks to first — a router's hotspot, an on-site wireless controller, a cloud-managed AP dashboard, or a standalone access point running its own captive portal. Whichever it is, wiring it to Kiwire is really two independent things that both have to be right:

  1. The redirect — the controller sends the guest's browser to Kiwire's login page. This is configured on the controller's own captive-portal / splash-page setting.
  2. RADIUS — the controller (or, for the UniFi console, Kiwire calling the vendor's own API instead) actually authorizes network access and reports session usage. The controller's RADIUS settings have to match its Device Controller record in Kiwire exactly.

Getting the redirect right with no RADIUS pointed at Kiwire shows a login page that can never grant access. Getting RADIUS right with no redirect means the guest never sees a login page in the first place. Both have to be done before a test login has any chance of working — see Before you leave site for the order to check them in.

The channels between a controller and Kiwire A guest device joins the SSID and opens a page. Four separate channels then connect the controller to Kiwire. One: the controller redirects the guest's browser to the portal page over HTTP, which only works if the walled garden allows Kiwire's host. Two: the controller sends RADIUS Access-Request and Accounting packets to Kiwire, authenticated by the shared secret and identified by the NAS-Identifier, which is the controller record's Identity. Three: Kiwire sends CoA or Disconnect packets back to the controller on the CoA port, 3799 by default, which must be open from Kiwire to the controller. Four, for UniFi console controllers only: Kiwire calls the vendor's API to authorise the guest's MAC and read usage instead of using RADIUS. Guest devicephone, laptopJOINS THE SSID, OPENS A PAGEController / APhotspot, WLC, cloud APKiwireportal + RADIUS + CoA1 HTTP REDIRECT TO THE PORTAL PAGE — THE WALLED GARDEN MUST ALLOW KIWIRE'S HOST2 RADIUS: ACCESS-REQUEST + ACCOUNTING — SHARED SECRET, NAS-IDENTIFIER = IDENTITY3 COA / DISCONNECT — COA PORT, DEFAULT 3799, OPEN FROM KIWIRE TO THE CONTROLLER4 VENDOR API INSTEAD OF RADIUS — AUTHORISES THE MAC, READS USAGE (UNIFI CONSOLE ONLY)
Channels 1 and 2 are configured independently — the redirect on the controller's own captive-portal setting, RADIUS on both the controller and Kiwire's Device Controller record. A portal page that appears but whose login never completes usually means channel 2 is wrong (secret, NAS-Identifier, port), not channel 1. Channel 3 is a third firewall rule, in the opposite direction.

Redirect URL and Identity ​

The controller's external portal setting points at https://<kiwire-host>/login/<slug>, where the slug names your controller type (mikrotik, meraki, tplink, …); your vendor's guide gives the exact one. The controller adds its own parameters — the guest's MAC, its own identity, and for most vendors the address of its own login page. After the guest signs in, Kiwire hands the login back: for most vendors it sends the guest's browser to the controller's login page with the username and password, and the controller then checks them against Kiwire over RADIUS. The UniFi console is the exception — Kiwire calls its API to authorize the guest's MAC instead. Which fields are passed, and whether the guest's original page is carried through, varies by vendor; see The redirect and the login config.

Every Device Controller record has an Identity — 4 to 120 characters, unique across the whole platform. Kiwire recognises a controller only by that value, never by its IP address, and it looks for it in two places: the identity the controller puts in the redirect, and the NAS-Identifier it sends in RADIUS (or, when a controller sends no NAS-Identifier, the AP MAC address in its Called-Station-Id). When the controller sends the same value in both, one record is enough; when they differ — common with cloud-managed controllers — you need a record for each. How to work out which values your controller sends is in Identity and Virtual NAS.

RADIUS shared secret ​

Point the controller's RADIUS authentication at port 1812 and accounting at port 1813 (UDP) on the RADIUS server address shown in the Setup Guide checklist ("Before you add your controller"). The shared secret is a short string (up to 64 characters) entered identically on both sides: the Shared Secret Key on the Device Controller record, and the RADIUS server entry on the controller. Kiwire picks the secret by the controller's Identity, so if the Identity doesn't match, or the secrets differ, RADIUS requests are silently dropped rather than producing an obvious error — a mismatched secret and an unreachable RADIUS server look the same from the guest's side (a login that never resolves). Meraki is an exception with a fixed secret; see its guide.

Two practical consequences: controllers that reach Kiwire from the same public IP address (behind one NAT, or relayed through a vendor cloud) must all use the same shared secret; and a newly added controller, or a changed secret, can take up to an hour to be accepted if the controller was already sending RADIUS before the record existed.

Most vendors also accept a CoA (Change of Authorization) request, which Kiwire uses to disconnect a guest or push a mid-session change. Kiwire sends it to the record's IP Address on its COA Port (3799 unless you change it), so that port has to be open from Kiwire's app server to the controller — the opposite direction to the RADIUS traffic from the controller to Kiwire.

Walled garden ​

Before a guest authenticates, their browser still has to be able to reach a short allow-list of hosts — the Kiwire portal host itself (for the login page and its assets) and any third-party hosts the portal uses, such as Google Fonts. This allow-list is configured on the controller or router, not in Kiwire. RADIUS is not part of it: RADIUS runs between the controller and Kiwire, not from the guest's browser. See Walled garden and redirect for the list and why a broken walled garden is one of the more common "guest can't reach the portal at all" causes.

Setup guides by vendor ​

Step-by-step setup for each vendor family, controller side and Kiwire side:

Which vendor page to read ​

The Vendor list on the Device Controller form offers 35 device types. The Supported controllers reference summarises each of them, grouped by how they talk to Kiwire:

  • Cloud-managed — the vendor's own cloud dashboard (UniFi, Meraki, Mist, EnGenius, Cambium, Huawei NCE/Cloud UGW, Ruijie Reyee) owns the access points; you configure Kiwire there once, for every site under that account.
  • On-premises controllers — a physical controller or gateway on site (Aruba, Cisco WLC, FortiGate/FortiAP, Huawei AC, Ruckus, TP-Link Omada, and others) fronts the APs and talks RADIUS to Kiwire directly.
  • Routers and standalone access points — MikroTik RouterOS, Peplink, standalone Ruckus and Zyxel APs, where the device itself runs the hotspot.
  • Gateway software — ChilliSpot/CoovaChilli, pfSense and WiFiDog, where the captive portal is a software component you configure rather than a vendor dashboard.
  • Other — CMCC, a generic entry, and Virtual NAS, which is an extra record for the name a cloud controller sends in RADIUS (see Identity and Virtual NAS).

The vendor guides and Other controllers show which types are available. Follow your vendor's guide rather than this page for the specifics — which fields are passed, which data-cap attribute if any, and which port needs to be reachable differ between vendors.

Last updated:

Kiwire platform documentation

Synchroweb