DOCUMENTATION

MikroTik Integration

Integrating Captivo with MikroTik Hotspot (PAP & CHAP)

Requirements: RouterOS with the Hotspot package and an active network interface (an ether port or bridge where guests connect — a network interface, not the WinBox GUI). Same family as pfSense/OPNsense: the portal HTML lives on the router, the form posts to the router's own login URL, RADIUS does the auth.

Two ways to do each step: the WinBox GUI (screenshots) or the terminal/CLI (command blocks). Both produce the same result — use whichever you prefer.

Works with both HTTP PAP and HTTP CHAP. With PAP the password travels in clear over the local hotspot redirect; with CHAP the template hashes it (MD5) using RouterOS's own md5.js. PAP is hardware-verified; CHAP was added afterwards — test it on your device. See Step 3 for the Login setting.

1Create the Hotspot

If you don't have a hotspot yet, run the Hotspot Setup wizard (WinBox → IP → Hotspot → Servers → Hotspot Setup) and pick your guest-facing interface/bridge — not the WAN. It creates the hotspot server, address pool and default profile.

Hotspot → Servers: the hotspot server, bound to your guest-facing interface/bridge (ether2 in this example), not the WAN.

CLI alternative:

# interactive wizard (asks for interface, address pool, DNS…)
/ip hotspot setup

2Define Captivo RADIUS on MikroTik

Add the Captivo RADIUS server and enable it for the hotspot service. The MikroTik router must also be registered as a NAS client on the Captivo side (IP + shared secret).

/radius add service=hotspot address=<RADIUS_IP> secret=<SECRET>
RADIUS menu → New: Service = hotspot, Address = Captivo RADIUS IP, your shared secret, ports 1812 / 1813.
Set the router's clock correctly (NTP). RouterOS often ships with NTP disabled, so the clock can be hours off. RADIUS accounting timestamps come from the router's clock — if it's wrong, active sessions won't appear in Captivo and your 5651 logs will have the wrong times. Enable NTP and the right timezone (WinBox: System → Clock and System → NTP Client; or: /system clock set time-zone-name=Europe/Istanbul and enable the NTP client).

3Hotspot profile: RADIUS + PAP/CHAP

/ip hotspot profile set <profile> use-radius=yes login-by=http-pap
# CHAP instead/also: login-by=http-chap   (or http-pap,http-chap)
Hotspot → Server Profiles → RADIUS tab: enable Use RADIUS and Accounting (Interim Update e.g. 1 min) so sessions appear in Captivo.
HTTP PAP and HTTP CHAP both work now (Login tab: IP → Hotspot → Server Profiles → your profile → Login). PAP sends the password in clear over the local redirect; CHAP hashes it with MD5 (more secure). For CHAP the template uses RouterOS's md5.js, which must exist in the hotspot directory — it's there by default, so keep the default files. PAP is hardware-verified; test CHAP on your own device.
Hotspot → Server Profiles → Login tab: HTTP PAP is enabled; you may also enable HTTP CHAP (see the note above).

Speed limits work out of the box: when a speed limit is set on the guest profile, Captivo sends both WISPr (for pfSense) and Mikrotik-Rate-Limit side by side, and each NAS reads the one it understands.

(Optional) Hotspot → User Profiles → default. Per-user speed limits come from RADIUS, so the default profile is usually fine.

4Walled Garden (important)

An unauthenticated guest must be able to reach Captivo and your SMS/email provider; otherwise the portal can't load the logo or verify the code.

/ip hotspot walled-garden add dst-host=*.captivo.io action=allow
# *.captivo.io covers app.captivo.io (wildcard supported)
# + your SMS / email provider domains
Hotspot → Walled Garden → New: Action = allow, Dst. Host = *.captivo.io.
Note: radius.captivo.io does NOT belong in the walled garden — that's the RADIUS server address (used in /radius add address=…). RADIUS is router↔server traffic (UDP 1812/1813), not the guest's web traffic. The walled garden only needs the web host the guest's browser reaches: *.captivo.io.

5Download and upload the portal template

  1. In Captivo go to Settings → Portal → Templates → MikroTik and download the ZIP.
  2. The ZIP contains login.html + alogin.html.
  3. In WinBox/WebFig open Files and upload them into the router's hotspot html-directory (default flash/hotspot), replacing the existing files. Keep the other default pages (status/logout/error).
Hotspot → Server Profiles → General: HTML Directory is where the portal files live (default 'hotspot').
Files: login.html / alogin.html uploaded into the hotspot directory.

This step is GUI/FTP only — there's no practical CLI for uploading the files. Use Files (drag & drop) or FTP.

How it works

The guest connects and MikroTik shows login.html. The guest enters their phone/email, the portal JS verifies it against the Captivo API, then fills a hidden form (username/password/dst=$(link-orig)) and posts it to $(link-login-only). MikroTik authenticates via RADIUS, accepts, shows alogin.html and redirects to the original page.

NAS-Identifier (optional extra isolation)

Optional. If you enable NAS-Identifier Verification in Captivo (Settings → RADIUS), the router must send that exact value. On RouterOS the NAS-Identifier attribute is the router's system identity name — so you set it by changing the identity:

  1. In Captivo go to Settings → RADIUS → NAS-Identifier, generate and copy the value.
  2. On the router, set the system identity to that value:
/system identity set name=<NAS-Identifier>
Caveats: (1) The system identity is also the router's display name everywhere (WinBox, etc.). (2) The "name:number" you may see in some RADIUS dashboards is the identity plus NAS-Port-Id (a separate attribute) — the actual NAS-Identifier is just the identity name. (3) These steps are based on MikroTik documentation and not yet verified on hardware by us — test before relying on it. If you can't set it, just leave NAS-Identifier Verification off in Captivo.

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

Was this article helpful?