Configure Ubiquiti Unifi

Checklist before proceeding with the Unifi configuration

  1. Please ensure the necessary ports are open to the controller per Unifi documentation, including port 8880 both directions or guest devices will be unable to load the splash page.
  2. You should receive an auth.html and index.html file from support. Ensure you have both files before attempting the configuration.
  3. The MAC of all APs that will be broadcasting the Guest WiFi signal need to be reported to support before attempting the configuration or guests could receive a hotspot deactivated message.


The following instructions outline how to setup a Ubiquiti UniFi network for the Smart WiFi Platform.  This guide covers details such as configuring RADIUS, walled garden entries, and captive portals.  This guide assumes that your Unifi controller is already operational and on a live network with adopted Access Points. Please make sure any firewall rules, web content filters, and other security measures have been configured to interface with the platform.

  1. Log into the controller, launch the correct site and click the settings icon in the bottom left.
  2. On the menu to the left click Advanced Features.
  3. On the Advanced Features page click ‘Add RADIUS profile’ and configure with:
    • Name: Smart RADIUS
    • RADIUS Settings
      1. Add two RADIUS Authentication servers using port 1812 and IPs and secret you receive from support.
      2. Enable Accounting: ON
      3. Add two RADIUS Accounting servers using port 1813 and IPs and secret you receive from support.
      4. Enable Interim Update: ON
    • Click ‘Apply Changes’ to save.
  4. On the menu to the left click WiFi.
  5. On the WiFi page click ‘Add New Guest Hotspot’ and configure with:
    • Enable Hotspot: ON
    • Name: Guest WiFi (or whatever you wish)

      Please do not use apostrophes in your SSID as it can cause issues with RADIUS authentication.

    • Guest Portal: ON
    • Authentication Type: RADIUS
    • RADIUS
      1. Profile: Smart RADIUS
      2. RADIUS Authentication Type: CHAP
      3. Disconnect Requests: OFF
    • Advanced
      1. Landing Page: Promotional URL
      2. Promotional URL: You will receive this from support
      3. Secure Portal: OFF
      4. HTTPS Redirection: OFF
      5. Redirect using hostname: OFF
      6. Enabled encrypted redirect URL: OFF
      7. Override Default Templates: ON
      8. Pre-Authorization Access: There have been reported issues with Pre authorization access for unauthorized guests on Unifi controllers using hostnames for their list. For this reason we provide the default entries for the platform as well as provide IP range lists for the platform. Please be sure you have include the IP ranges for your environment in your configuration if you’re experiencing issues with guests loading the splash page.
        Hostnames
        Please use the entries contained inside the default walled garden and include any extra entries included by your provider.
        US-A IP Ranges
        This is the template for hotspots in the US-A environment only and covers Ads4WiFi Pre-Authentication AdSpaces.
        US-B IP Ranges
        This is the template for hotspots in the US-B environment only and covers Ads4WiFi Pre-Authentication AdSpaces.
        Social media IP Ranges
        This template is for the different social media login methods available in the platform.
    • Press ‘Apply Changes’ to save.
  6. Final Step

    Place the two html files that you downloaded from the dashboard in step one to your UnifFi controller hotspot directory. If using a cloudkey please use a SFTP program like WinSCP.
    You can find your site directory name by looking at the URL when viewing the site on the controller.

    Typical file location examples are below.(depending on the UniFi controller):
    Please note you will typically use your site auto generated folder name instead of default.
    Dream Machine: /data/unifi/data/sites/default/app-unifi-hotspot-portal
    CloudKey: /srv/unifi/data/sites/default/app-unifi-hotspot-portal
    Windows: C:\Users\<username>\Ubiquiti UniFi\data\sites\default\app-unifi-hotspot-portal
    MAC: ~/Library/Application Support/UniFi/data/sites/default/app-unifi-hotspot-portal
    Linux: /usr/lib/unifi/sites/default/app-unifi-hotspot-portal


Troubleshooting Splash page

  1. Please do not use apostrophes in the SSID name as they can cause issues with RADIUS authentication.
  2. If devices are redirected but the device hangs on the controller IP please ensure port 8880 is open to the Unifi Controller.
  3. If devices are redirected and port 8880 is open to the controller please ensure that the ‘Secure Portal’ option is turned OFF.
  4. If devices present an certificate error please ensure https redirection is disabled.
  5. If a hotspot deactivated message is presented please ensure all the AP MACs have been reported to support.
  6. If devices are redirected to the splash page URL but the page fails to load please ensure the Allowed Authorization Access list has been properly configured.
  7. If the internal captive portal from the Unifi controller is displayed instead of the hotspot splash page make sure ‘Override Default Templates’ is ON and the index and auth files have been placed on the correct site directory.
  8. If devices load the splash page properly but after pressing connect the splash page is loaded again please ensure you’ve used the correct RADIUS servers for your environment and the RADIUS Authentication password is correct and less than 15 characters.
  9. If devices are able to authenticate but you don’t see connections posted in the dashboard please ensure you’ve used the correct RADIUS servers for your environment and the RADIUS Accounting password is correct.

Unifi Resources

The following links are to Unifi community resources that can help with troubleshooting the captive portal experience for guests.


Disclaimer on hardware configuration guides in the KB:

This equipment has been integrated and tested in our labs with the Smart WiFi Platform using the firmware versions below.

Ubiquiti UniFi CloudKey Version 6.4.54 Firmware 1.1.19
Ubiquiti UniFi UAP-AC-Lite 5.43.43.12741

LIMITED HARDWARE SUPPORT: Hardware manufacturers frequently make changes to firmware, controllers and GUI’s. The information below may be out of date or images may be different and is to be used as a general reference guide. We do offer additional limited support to help with trouble-shooting and we highly recommend that you have a hardware support agreement and/or access to a hardware support engineering representative from the manufacturer.

Updated on September 22, 2021

Was this article helpful?

Related Articles