UniFi Integration

Guest WiFi on Ubiquiti UniFi using a small local Connector bridge — no RADIUS and no HTML upload. The UniFi controller redirects guests to Captivo's hosted portal, and the Connector grants access on the controller once the guest verifies.

UniFi works differently from the firewall integrations: instead of RADIUS, a lightweight Connector agent runs on your network and bridges Captivo to your UniFi controller. The agent only connects outbound — your UniFi admin credentials stay on your network and are never sent to the cloud.

No session data in this setup. The UniFi integration authorises guests through the controller's own API via the Connector, not over RADIUS accounting. Nothing writes session records, so Active Sessions stays empty and the session-based figures (duration, data usage) are not produced. Guest records, logins and the portal itself work normally. If you need live session tracking, use a RADIUS-based integration (pfSense, OPNsense, MikroTik, FortiGate).

The Connector is a cloud (SaaS) feature. On self-hosted / on-premise installations the Connectors page is not available; this guide applies to app.captivo.io.

1Add a Connector in Captivo

Go to Settings → Connectors → Add Connector. Give it a name, choose UniFi as the product, and create it. Captivo shows a one-time pairing code (valid 15 minutes) plus a ready-to-run docker command with your pairing code and portal URL already filled in.

2Run the Connector on your network

On any machine with Docker on the SAME network as your UniFi controller, run the command shown in the dashboard. Replace UNIFI_URL, UNIFI_USER, UNIFI_PASS and UNIFI_SITE with your controller's values (use a local controller account allowed to authorize guests). CAPTIVO_URL and PAIR_CODE are pre-filled for you.

bash

docker run -d --name captivo-connector --restart unless-stopped \
  -v captivo-connector:/data \
  -e CAPTIVO_URL=https://app.captivo.io \
  -e PAIR_CODE=<code-from-dashboard> \
  -e UNIFI_URL=https://192.168.1.1 \
  -e UNIFI_USER=admin \
  -e UNIFI_PASS=YOUR_PASSWORD \
  -e UNIFI_SITE=default \
  captivoio/connector:latest

The Connector enrolls automatically and starts polling Captivo. Within a few seconds the Connectors page shows it as Online. No inbound ports or port-forwarding are required.

3Point UniFi's guest portal at Captivo

In UniFi Network → Settings → Guest Hotspot/Portal, enable the portal and set Authentication to 'External Portal Server'. Set the External Portal Server URL to your hosted portal address — https://app.captivo.io/p/<your-tenant-slug> — which is shown, copyable, in the Captivo pairing dialog.

4Pre-Authorization / Walled Garden — important

In the same Guest Hotspot settings, add *.captivo.io to the Pre-Authorization / Walled Garden list so the portal can load and reach Captivo before the guest signs in.

This is the #1 cause of 'the portal opens but no SMS arrives'. The portal's JavaScript fetches the verification code from app.captivo.io, so that domain must be reachable before sign-in. You do NOT need to allowlist your SMS provider's domain — Captivo sends the SMS from its own servers.

5Test the guest flow

Connect a phone to the guest WLAN. UniFi redirects it to the branded Captivo portal; the guest verifies via SMS, voucher or any other enabled method; Captivo signals the Connector, which authorizes the device on the UniFi controller — and the guest is online. Sessions and identity logs appear in the Captivo dashboard.

Troubleshooting — Connector shows Offline: check it can reach app.captivo.io outbound and that UNIFI_URL/USER/PASS are correct (see the container logs). Portal opens but no SMS: add *.captivo.io to the walled garden (step 5). Guest verifies but stays offline: confirm the Connector is Online and the controller account is allowed to authorize guests.

For product-wide problems: The portal does not open · Sign-in is rejected · Sessions do not appear