RouterOS HotSpot: Authentication Methods, RADIUS, and Troubleshooting

RouterOS HotSpot: Authentication Methods, RADIUS, and Troubleshooting

Configuration Guide	md-vcsi
Date	March 23, 2026
RouterOS Version	7.x

Overview

RouterOS HotSpot is a captive-portal gateway that intercepts unauthenticated client HTTP requests and redirects them to a login page. This guide covers:

• The full set of authentication methods available and when to use each
• RADIUS integration for centralised user management and accounting
• Walled garden configuration for pre-authentication access
• User profiles for bandwidth and session control
• Troubleshooting the most common HotSpot problems

For initial setup (wizard walkthrough, DHCP pool, IP address assignment) see HotSpot Portal Setup.

---

Authentication Methods

HotSpot supports multiple authentication methods, configured in the server profile via the login-by property. Multiple methods can be combined as a comma-separated list; the router will accept whichever the client presents.

/ip hotspot profile
set [find name=hsprof1] login-by=https,http-chap,cookie,mac

Method reference

Method	login-by value	How it works
HTTP-CHAP	http-chap	Challenge-response over HTTP. The router sends a random challenge; the browser hashes credentials + challenge with MD5 before submitting. Avoids sending passwords in plaintext over plain HTTP.
HTTP-PAP	http-pap	Password sent in plaintext (POST). Only use on trusted networks or when HTTPS is enforced separately.
HTTPS login	https	Login page is served over TLS. Credentials travel encrypted. Requires a certificate on the profile. Recommended for all deployments.
MAC authentication	mac	Client MAC address is used as both username and password. No user interaction required. Suitable for kiosks, IoT devices, or pre-registered devices. MAC addresses are trivially spoofable — combine with RADIUS for stronger control.
MAC cookie	mac-cookie	Stores a cookie tied to the client MAC. On the next visit from the same browser/device, the router re-authenticates silently without asking for credentials again.
Cookie	cookie	Browser cookie only — no MAC binding. Convenient for repeat visitors but does not persist across browsers or private sessions.
Trial access	trial	Grants time-limited access without credentials. Controlled by trial-uptime-limit and trial-user-limit in the server profile.
Voucher / username-password	(any credential method)	Vouchers are standard HotSpot users distributed as printed or emailed username/password pairs. The delivery method is external; the auth method is HTTPS or HTTP-CHAP.

Configuring each method

HTTPS login (recommended)

HTTPS login requires a certificate trusted by the client browser (or at least a self-signed cert that users accept).

# Create a self-signed certificate
/certificate
add name=hotspot-cert common-name=hotspot.example.com \
    key-usage=digital-signature,key-encipherment,tls-server \
    days-valid=3650
sign hotspot-cert

# Assign to the HotSpot profile
/ip hotspot profile
set [find name=hsprof1] \
    ssl-certificate=hotspot-cert \
    https-redirect=yes \
    login-by=https,cookie

Note: With https-redirect=yes, the router rewrites the initial HTTP redirect to HTTPS before presenting the login page.

HTTP-CHAP

HTTP-CHAP works without a certificate and is the safe default for HTTP-only portals.

/ip hotspot profile
set [find name=hsprof1] login-by=http-chap,cookie

The challenge is embedded in the login page HTML by the HotSpot servlet; the standard login.html template handles this automatically.

MAC authentication

MAC auth does not require user interaction. The router tries to authenticate the client’s MAC address as a username.

# Enable MAC auth in the profile
/ip hotspot profile
set [find name=hsprof1] login-by=mac,mac-cookie,https

# Add a local MAC user
/ip hotspot user
add name=DC:A6:32:11:22:33 password=DC:A6:32:11:22:33 \
    profile=devices comment="Raspberry Pi kiosk"

For RADIUS-based MAC auth, see RADIUS Integration.

Trial access

Trial grants unauthenticated users temporary internet access before they create an account or pay.

/ip hotspot profile
set [find name=hsprof1] \
    login-by=trial,https,cookie \
    trial-uptime-limit=30m \
    trial-user-limit=2

trial-user-limit controls how many simultaneous trial sessions are allowed per unique MAC. Set trial-uptime-limit=0s for unlimited trial time (open access).

Vouchers

Vouchers are pre-created local users distributed as credentials.

# Generate batch vouchers
:for i from=1 to=50 do={
    :local pass [/certificate scep-client add]
    :local name ("v-" . [:tostr $i])
    :local pw [ :rndstr length=8 from="ABCDEFGHJKLMNPQRSTUVWXYZ23456789" ]
    /ip hotspot user add name=$name password=$pw \
        profile=voucher limit-uptime=24h
    :log info ("voucher: " . $name . " / " . $pw)
}

The login page method for vouchers is typically HTTPS or HTTP-CHAP. For scalable voucher management, use User Manager.

---

User Profiles

User profiles define session limits, bandwidth caps, and behavioural settings that apply to all users assigned to that profile.

/ip hotspot user profile
add name=guest \
    session-timeout=4h \
    idle-timeout=30m \
    rate-limit=5M/10M \
    shared-users=1 \
    add-mac-cookie=yes

add name=premium \
    session-timeout=0s \
    idle-timeout=0s \
    rate-limit=50M/100M \
    shared-users=3

add name=voucher \
    session-timeout=24h \
    idle-timeout=1h \
    rate-limit=10M/20M \
    limit-bytes-in=2000000000 \
    limit-bytes-out=2000000000 \
    shared-users=1

Key profile properties

Property	Description
session-timeout	Maximum session duration. 0s = unlimited.
idle-timeout	Disconnects client after this period of inactivity. 0s = unlimited.
rate-limit	Bandwidth cap in rx/tx format. Supports burst. See rate limit syntax.
shared-users	How many simultaneous logins are allowed per username.
limit-bytes-in	Data quota for inbound traffic (bytes). 0 = unlimited.
limit-bytes-out	Data quota for outbound traffic (bytes). 0 = unlimited.
add-mac-cookie	When yes, sets a MAC cookie after login to allow transparent re-auth.
open-status-page	Whether to show the status page after login (always, http-login, or never).

Assigning users to profiles

/ip hotspot user
add name=alice password=secure profile=premium
add name=bob   password=secret  profile=guest

---

RADIUS Integration

RADIUS allows centralised authentication and accounting for HotSpot. The router acts as a RADIUS client (NAS), forwarding authentication requests and sending accounting records to an external RADIUS server.

Add the RADIUS server

/radius
add service=hotspot \
    address=10.0.1.10 \
    secret=StrongRadiusSecret \
    authentication-port=1812 \
    accounting-port=1813 \
    timeout=3000ms \
    accounting=yes

Enable RADIUS in the HotSpot profile

/ip hotspot profile
set [find name=hsprof1] \
    use-radius=yes \
    radius-default-domain=example.com \
    radius-location-id="site-a" \
    radius-location-name="Building A"

Property	Description
use-radius	Forward authentication to RADIUS (yes/no).
radius-default-domain	Appended to usernames that lack a domain (user@domain).
radius-location-id	Value sent in RADIUS attribute NAS-Identifier.
radius-location-name	Sent in Called-Station-Id to identify the site.

Enable accounting and interim updates

/radius
set [find address=10.0.1.10] accounting=yes

/ip hotspot profile
set [find name=hsprof1] interim-update=5m

# Accept RADIUS-initiated disconnect (CoA / DM)
/radius incoming
set accept=yes port=3799

RADIUS attributes sent by RouterOS (Access-Request)

RADIUS Attribute	Value
User-Name	HotSpot username
User-Password or CHAP-Password	Credential (method-dependent)
NAS-IP-Address	Router’s hotspot IP
NAS-Port-Type	Wireless-802.11 or Ethernet
Calling-Station-Id	Client MAC (format XX-XX-XX-XX-XX-XX)
Called-Station-Id	Hotspot interface MAC + SSID
Framed-IP-Address	Client IP from the DHCP lease

RADIUS attributes accepted in Access-Accept

Attribute	Effect
Session-Timeout	Override session-timeout from profile
Idle-Timeout	Override idle-timeout
Framed-IP-Address	Assign a specific IP to the client
Reply-Message	Displayed to user on login page
Mikrotik-Rate-Limit	Bandwidth cap (rx/tx [burst-rx/burst-tx ...])
Mikrotik-Group	Assigns the user to a local HotSpot user profile
Mikrotik-Recv-Limit	Inbound data quota in bytes
Mikrotik-Xmit-Limit	Outbound data quota in bytes
Mikrotik-Total-Limit	Combined data quota in bytes

MAC authentication via RADIUS

/ip hotspot profile
set [find name=hsprof1] login-by=mac,https

# RADIUS server receives Access-Request where User-Name = MAC address
# (e.g., DC:A6:32:11:22:33) and shared secret is the RADIUS secret.
# Respond with Access-Accept to allow, Access-Reject to deny.

FreeRADIUS example

/etc/freeradius/3.0/clients.conf

client routeros {
    ipaddr = 192.0.2.1
    secret = StrongRadiusSecret
    nas_type = other
}

/etc/freeradius/3.0/mods-config/files/authorize

guest  Cleartext-Password := "guest123"
       Mikrotik-Rate-Limit := "5M/5M",
       Session-Timeout := 3600,
       Reply-Message := "Welcome, guest"

premium  Cleartext-Password := "prem456"
         Mikrotik-Group := "premium",
         Reply-Message := "Premium access granted"

Ensure the MikroTik dictionary is loaded:

# Verify /etc/freeradius/3.0/dictionary includes:
$INCLUDE /usr/share/freeradius/dictionary.mikrotik

Verify RADIUS connectivity

# Check RADIUS client status and counters
/radius monitor 0

# Watch live hotspot auth log
/system logging add topics=hotspot,debug action=memory
/log print follow where topics~"hotspot"

---

Walled Garden

The walled garden allows unauthenticated clients to reach specific hosts or URLs before logging in. This is needed for:

• OS captive portal detection endpoints
• Payment gateway or registration pages
• Social login OAuth flows

RouterOS has two separate walled garden tables:

Table	CLI path	Matches
HTTP walled garden	/ip hotspot walled-garden	HTTP Host header + URL path
IP walled garden	/ip hotspot ip-walled-garden	Destination IP, protocol, port

HTTP walled garden

/ip hotspot walled-garden

# Allow a specific domain (all paths)
add dst-host=payment.example.com action=allow \
    comment="Payment portal"

# Allow domain with wildcard path
add dst-host=api.oauth-provider.com dst-path=^/oauth action=allow \
    comment="OAuth endpoint"

IP walled garden

Use for HTTPS destinations (which cannot be matched by hostname at layer 7), CDNs, or non-HTTP protocols.

/ip hotspot ip-walled-garden

# Allow HTTPS to a payment server
add dst-address=198.51.100.10 protocol=tcp dst-port=443 action=accept \
    comment="Payment gateway HTTPS"

# Allow all traffic to a captive portal check server
add dst-address=1.2.3.4 action=accept \
    comment="CNA detection server"

OS captive network assistant (CNA) endpoints

Allow these to prevent OS-level “no internet” detection from breaking the portal flow:

/ip hotspot ip-walled-garden

# Apple
add dst-address=17.253.144.10 action=accept comment="Apple CNA"

# Windows / Microsoft
add dst-address=13.107.4.52  action=accept comment="MSFT NCA"
add dst-address=96.16.54.99  action=accept comment="MSFT NCA 2"

# Android / Google
add dst-address=142.250.0.0/15 action=accept comment="Google CNA range"

Tip: Add the router’s own IP (hotspot-address) to the IP walled garden to allow the login page to be loaded without authentication.

Dynamic walled garden via RADIUS

The Mikrotik-Walled-Garden-List vendor attribute can inject per-session walled garden entries on authentication. This allows personalised access before full login (e.g., showing a payment page).

---

Troubleshooting

Diagnostic commands

# View active (authenticated) sessions
/ip hotspot active print

# View all connected hosts (including unauthenticated)
/ip hotspot host print

# View hotspot server state
/ip hotspot print detail

# View walled garden rules
/ip hotspot walled-garden print
/ip hotspot ip-walled-garden print

# View RADIUS counters
/radius monitor 0

# Enable debug logging
/system logging add topics=hotspot,debug action=memory
/system logging add topics=radius,debug action=memory
/log print follow

Common issues

Clients not redirected to login page

Symptoms: Client gets an error or reaches the internet without logging in.

Checks:

1. Verify the HotSpot is running on the correct interface:

   /ip hotspot print

2. Confirm DHCP is assigning addresses from the hotspot pool:

   /ip dhcp-server lease print

3. Confirm NAT masquerade is present for the WAN interface:

   /ip firewall nat print where chain=srcnat

4. Confirm the client is on the hotspot interface/bridge — not bypassing it through another port.

HTTPS sites not triggering redirect

Why: HTTPS traffic cannot be transparently intercepted the same way HTTP can. The HotSpot only intercepts and redirects plain HTTP (tcp/80). HTTPS connections will fail with a certificate error or connection refused until the client authenticates.

Solutions:

• Enable https-redirect=yes in the profile so the initial HTTP redirect lands on an HTTPS login page.
• Use OS CNA endpoints (walled garden) so devices display the “sign in to network” prompt automatically.
• Consider HTTPS certificate on the portal to reduce browser warnings.

Redirect loop

Symptoms: Browser keeps bouncing between pages without reaching the login form.

Causes & fixes:

• dns-name in the profile is not resolvable by clients. Verify the router resolves the name and DNS is configured in the DHCP network:

  /ip dhcp-server network print

• The hotspot address is not set correctly in the profile. The hotspot-address must match the router’s IP on the hotspot interface.
• The login page (login.html) uses a wrong form action URL. Default templates are correct; check for customisations.

SSL certificate errors on login page

Symptoms: Browser shows certificate warning before displaying the login page.

Checks:

1. Is the certificate installed and valid?

   /certificate print detail where name=hotspot-cert

2. Is the certificate assigned to the profile?

   /ip hotspot profile print where name=hsprof1

3. Does dns-name in the profile match the certificate CN or SAN?
4. Is the certificate’s validity period current (not-after > today)?

For self-signed certs, users must accept the warning once; for production use a trusted CA certificate.

RADIUS authentication failures

Symptoms: Users get “rejected” or “invalid username or password” despite correct credentials.

Checks:

1. Verify RADIUS server is reachable:

   /tool ping 10.0.1.10
   /radius monitor 0

2. Verify the shared secret matches on both router and RADIUS server.
3. Check timeout — increase if RADIUS server is slow:

   /radius set [find] timeout=5000ms

4. Check RADIUS server logs for the Access-Request and reason for Access-Reject.
5. Ensure use-radius=yes is set in the HotSpot profile.

MAC authentication not working

Symptoms: MAC-auth clients are redirected to login page instead of passing through.

Checks:

1. Confirm mac is in login-by:

   /ip hotspot profile print where name=hsprof1

2. For local MAC users, confirm the username is the MAC in the format the router sends (check Calling-Station-Id in RADIUS logs or the /ip hotspot host print output for the exact format).
3. Confirm the local user or RADIUS entry exists for that MAC.

Walled garden bypass not working

Symptoms: Unauthenticated clients cannot reach allowed hosts.

Checks:

1. Use the correct table: HTTP walled garden for plain HTTP by hostname; IP walled garden for HTTPS or IP-based rules.
2. Verify the rule is active:

   /ip hotspot walled-garden print
   /ip hotspot ip-walled-garden print

3. Note: HTTP walled garden matches by Host: header. CDNs and load-balanced services may use IP addresses that don’t match the hostname — use the IP walled garden for those.
4. Check that the action is allow (HTTP) or accept (IP walled garden).

HotSpot not starting / interface not appearing

Symptoms: interface=none in /ip hotspot print or errors on setup.

Checks:

1. The interface must have an IP address assigned before adding the HotSpot:

   /ip address print where interface=<hotspot-iface>

2. Only one HotSpot server can run per interface. Verify no duplicate:

   /ip hotspot print

3. After fixing the interface assignment, re-run the wizard or re-add the server:

   /ip hotspot setup

---

See Also

• HotSpot Portal Setup — wizard, DHCP, NAT, and first-time configuration
• User Profiles and Data Quotas — rate limits, session control, quotas
• Walled Garden — detailed walled garden configuration reference
• RADIUS Integration — full RADIUS attribute reference and accounting
• User Manager — built-in RADIUS for voucher and multi-site management
• Certificates — certificate management for HTTPS login