Port forwarding is a required step when setting up Spotipo's captive portal with UniFi controllers that don't have public IP addresses. Without proper port forwarding, your UniFi controller can't communicate with Spotipo's servers, meaning your splash page won't load and guests can't authenticate on your WiFi network.
This guide shows you how to configure port forwarding on your router to direct external traffic from your public IP address to your UniFi controller's private IP address. This applies to Cloud Key devices, Dream Machines (UDM/UDM Pro), and self-hosted UniFi controllers behind NAT.
When you need port forwarding:
Your UniFi controller doesn't have a public IP address
You're not using Spotipo's reverse tunnel option
Your controller sits behind a router or firewall, performing NAT
Your controller status in Spotipo shows "Not Reachable"
What you'll accomplish:
Assign a static IP address to your UniFi controller
Configure port forwarding rules on your router
Enable Spotipo to reach your controller for guest authentication
Alternative: If port forwarding isn't possible (double NAT, CGNAT, or Starlink), use Spotipo's reverse tunnel instead.
Why and when to use Port Forwarding?
For setting up a Spotipo captive portal with UniFi controllers, Port forwarding is necessary as it directs traffic from your public IP address to your UniFi controller using its private IP address and port number.
Setting up static IP address for UniFi controller?
Find the Device's MAC Address:
Go to the UniFi Controller and navigate to UniFi Devices.
Select the device you need to configure. The MAC address will be displayed in the panel on the right.
Routers with Graphical Interface:
Log into your router's web interface.
Find the Static IP, DHCP Reservation or similar option (name varies by router).
Add a new entry with the device's MAC address and assign the desired static IP address.
Router with CLI-Based Interface (Example for Cisco IOS):
enable configure terminalip dhcp pool <pool_name> network <ip address> <mask> default-router <router_ip> dns-server <dns-server_ip>host <ip_address> <mask> hardware-address <MAC_Address>exitwrite memory
Setting up port forwarding
Prepare Your Router:
Ensure that your UniFi device has a static IP address assigned.
Configure Port Forwarding on Your Router:
Routers with Graphical Interface:
Find the Port Forwarding, Port Mapping, Virtual Server, or NAT option (name varies by router).
Add a new rule to forward traffic to the UniFi device's IP address.
Use TCP protocol and port 443 (used by UniFi controllers).
CLI based interface (example for Cisco IOS)
enable configure terminalinterface <Outside_Interface> ip nat outsideinterface <Inside_Interface> ip nat insideip nat inside source static tcp <UniFi_ip> 443 interface <Outside_Interface> 8080write memory
Verify the Configuration:
Check that the port forwarding rule is active and working.
Your UniFi Captive Portal Should Now Work
With port forwarding properly configured, Spotipo can communicate with your UniFi controller to authenticate guests. Test your setup by connecting a device to your guest WiFi—the Spotipo splash page should appear within seconds.
What to do next:
Customize your splash page design to match your branding
Set up email capture to collect guest contact information
Port forwarding not working? Common issues and solutions:
Double NAT: If your modem and router both perform NAT, port forwarding becomes complex. Consider using Spotipo's reverse tunnel instead.
CGNAT or Starlink: Some ISPs use carrier-grade NAT, which blocks inbound connections. Use reverse tunnel setup as an alternative.
Firewall blocking: Even with port forwarding, UniFi's built-in firewall may block Spotipo. Whitelist Spotipo IPs in your firewall rules.
Dynamic public IP: If your public IP changes frequently, set up DDNS (Dynamic DNS) to maintain connectivity.
Alternative: Skip Port Forwarding with Reverse Tunnel
If port forwarding is too complex or impossible in your network environment, Spotipo offers a reverse tunnel option that requires no router configuration. The tunnel creates an outbound connection from your controller to Spotipo's servers, bypassing the need for inbound port forwarding.
Still stuck? Contact support via live chat or email us at [email protected] with your controller model and network setup details.