Ubiquiti UniFi

How to connect a UniFi Network application (UniFi OS console, self-hosted or cloud-hosted) to Kiwire as an external guest portal.

Device type in Kiwire	UBNT Console
Redirect URL	UniFi's External Portal Server points at Kiwire; guests land on https://<kiwire-host>/login/ubnt-console automatically
RADIUS	not used — Kiwire authorises guests through the UniFi API
Identity must equal	the AP MAC (one record per AP)
Disconnect / live changes (CoA)	yes, through the UniFi API (see Limits)
Data caps	yes — the profile's time, speed and data limits are passed to UniFi when the guest is authorised

Which entry to pick

• UBNT Console: any current UniFi Network application — UniFi OS consoles (UDM, UDR, UCG, Cloud Key) and self-hosted or cloud-hosted controllers. This page covers it.
• Ubiquiti Controller and Ubiquiti: Status: not available yet — these controller types are listed in Kiwire but a guest login does not complete on them today. Contact Synchroweb before deploying one.

Before you start

From Kiwire: your host name <kiwire-host>.

From UniFi:

• the address Kiwire can reach the Network application on (IP or host name, and port if it is not 8443 — UniFi OS consoles normally use 443);
• the site ID (the short name in the UniFi URL, default for the first site);
• either an API key (UniFi OS: Network › Integrations › Create New API Key) or a local admin username and password;
• the MAC address of every AP that serves the guest SSID.

The Kiwire application server must be able to reach that UniFi address over HTTPS. For a console behind a firewall, open the port to Kiwire (ask Synchroweb for the address Kiwire connects from).

On the controller

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

1. Settings › WiFi › your guest SSID › turn on Hotspot / Guest Hotspot (older versions: Settings › Guest Control).
2. Set authentication to External Portal Server and enter the Kiwire portal address. If your UniFi version only accepts an IPv4 address here, ask Synchroweb which address to use.
3. Leave HTTPS redirection to UniFi's defaults; UniFi sends the guest to /guest/s/<site>/ on that address and Kiwire forwards it to the portal with the AP MAC, client MAC, SSID and original URL.
4. Pre-Authorization Access (walled garden): add <kiwire-host>, fonts.googleapis.com, fonts.gstatic.com and anything your portal design loads. See Walled garden and redirect.
5. Do not configure a RADIUS profile for this SSID — authorisation happens through the API.

Let Kiwire set it up

Select a UBNT Console controller in Device › Controllers and click Site Provisioning. Kiwire works out the settings for the UniFi site — External Portal Server at Kiwire's address, Kiwire (and your portal's fonts, and optionally Google/Facebook/Microsoft sign-in and the payment gateways) under Pre-Authorization Access, and, if you type its name, the SSID switched to guest hotspot.

• When automatic setup is switched on for your Kiwire and the controller has the UniFi address plus an API key or username/password, Kiwire applies the settings itself, checks them, and lists any access points on the site that have no controller record in Kiwire yet. Your existing Pre-Authorization entries are kept.
• Otherwise you get the same settings as numbered steps to follow in the UniFi application.
• The guest captive portal uses no RADIUS — UniFi does not use RADIUS for Kiwire's guest login.

Sites that already have settings. When Kiwire applies the settings itself it first reads the UniFi site and shows every change as Now on the site → After:

• Preview lists the changes without touching anything.
• Changes that would overwrite something already in use are marked overwrites and need your confirmation before anything is applied — for example a site that signs guests in with UniFi vouchers or another portal (the guest sign-in method covers the whole site, so every guest SSID moves to Kiwire), an SSID whose security would change (everyone on it is disconnected), or a RADIUS profile other SSIDs use. Brand-new objects need no confirmation.
• What was on the site before is saved with each run (stored encrypted). Revert — straight after applying, or later from the history tab — puts the site back exactly as it was: the previous sign-in method, SSID security and passwords, the previous RADIUS profile, and it removes the SSIDs, RADIUS profile and Pre-Authorization entries Kiwire added. Your own Pre-Authorization entries and other settings are never removed.

WiFi Enterprise (802.1X). Tick WPA-Enterprise as well as (or instead of) Captive portal. Kiwire creates a RADIUS profile called kiwire-radius on the site, pointing at Kiwire's RADIUS with this controller's shared secret and accounting turned on. If you type an Enterprise SSID, that SSID is set to WPA2-Enterprise, WPA2/WPA3-Enterprise or WPA3-Enterprise with that profile — created if it does not exist, switched if it does (switching disconnects everyone on it). Users then sign in with their own Kiwire account. RADIUS recognises each access point by its MAC, so every AP needs a UBNT Console record with this controller's shared secret.

In Kiwire

1. System › Device Controller › add one record per AP:
   • Vendor: UBNT Console.
   • Identity: the AP's MAC exactly as UniFi sends it (normally lower case with colons, aa:bb:cc:dd:ee:ff; Controller Test shows it).
   • Shared Secret Key: required by the form; any value up to 64 characters (it is not used by UniFi).
   • API Key and Site ID (shown only for this vendor): the key from Integrations, and the site short name (blank = default).
   • Advanced Configuration: Username / Password of a UniFi local admin if you do not use an API key, and IP Address = the UniFi address, with :port if it is not 8443.
   • Seamless Roaming Interval: how long a guest who leaves the Wi-Fi can come back without signing in again. See When a guest leaves. Each AP record needs the same UniFi address and credentials. Each record counts toward your licence's device limit.
2. Check the redirect parameters with Redirect and login config: Kiwire reads id (client MAC), ap, ssid and url.
3. Add a zone rule and journey: Controllers and zones, Portal designer.

Test it

1. Portals › Troubleshoot › Controller Test › Start Capture, then connect a phone to the guest SSID. Check that id and ap arrive and the AP shows as registered.
2. Log in as a real guest; the phone should go online straight after the portal, and the guest appears as authorised in UniFi's client list. Use a test profile with a short validity (for example 1 hour) and a speed limit, and check that UniFi shows the same expiry and limits for the guest.
3. Reporting › Login › Active Session lists the guest. Usage figures are collected from UniFi every few minutes, so they lag behind slightly.
4. Disconnect the test guest from Kiwire and confirm in the UniFi console that they are no longer authorised.

Limits to know

• Profile limits are set once, at login. When Kiwire authorises the guest it passes the profile's time limit (in minutes), upload and download speed, and data quota (in MB). UniFi then enforces them. If Kiwire cannot read the guest's limits at that moment, the guest is authorised for 8 hours with no speed or data limit.
• Give every profile a real validity. Set a time limit on every profile so UniFi always has an expiry for the guest.
• Live changes. Disconnecting a guest, or changing their profile, from Kiwire goes to the UniFi console with the same address, login and Site ID as sign-in. Step 4 of Test it checks this path.
• One record per AP: a new AP that is not registered in Kiwire shows guests an error until you add it.

When a guest leaves

Kiwire checks the UniFi console every few minutes. When a guest's device is no longer connected, Kiwire ends their session. The Seamless Roaming Interval on the record then decides what happens if they come back:

Setting	A guest who comes back…
Disabled	signs in again every time. A phone that drops off the Wi-Fi for a few minutes (for example, while asleep) may be asked to sign in again.
1 Hour / 1 Day / 1 Week / 1 Month	reconnects without signing in if they return within that time. After it, they sign in again.
Unlimited	reconnects without signing in until the time they got at sign-in runs out.

Whatever you choose, the time and data limits from sign-in still apply. Use the same setting on every AP record of a site, because a guest can come back through any AP.

Vendor reference

• UniFi Hotspots and Captive Portals (Ubiquiti Help Center)
• External Hotspot API for Authorization Clients (Ubiquiti Help Center)
• Required Ports Reference (Ubiquiti Help Center)