Guest access – Ubiquiti UniFi

In this topic, you will learn how to configure Ubiquiti UniFi to work together with the Portnox™ Cloud captive portal for guest user authentication.

Before you begin configuring your controller, you must configure the guest network in Portnox Cloud and note down the values of the following fields:

Captive Portal ID

For example: b2973887-1274-45c4-91d0-4a342a861c76-homeworld

(Also shown in the PORTNOX_ECP_ID field)
Captive Portal Proxy URL (for UniFi)

For example: https://b2973887-1274-45c4-91d0-4a342a861c76-homeworld.proxy.guests.portnox.com
The API access token generated in Settings > Profile Settings > CLOUD API TOKENS

For example: mk1yiGyEatNa_qFR8ibnr9HWht4

You will need these values later. We recommend that you keep your Portnox Cloud configuration open in another browser tab for easy copying and pasting.

Important:

This guide provides general instructions for integrating Portnox Cloud with specific third-party devices. While we aim to provide helpful examples for commonly used models, configurations may vary across manufacturers, models, and environments. As a result, we cannot guarantee that these steps will work in every scenario. For questions or issues related to RADIUS setup – which is an industry standard and not specific to Portnox – or device-specific settings and troubleshooting, we recommend consulting the device manufacturer’s documentation and contacting their support team. While Portnox Support is happy to assist where possible, please note that detailed configuration of third-party devices is typically best handled by the manufacturer.

Important:

All values in this configuration are examples. Make sure to adjust the configuration to your individual profile names, RADIUS server addresses, ports, and keys by replacing the values that are presented as underlined italics.

Note:

This setup was tested on a UniFi Network Server, UniFi Dream Router, and UniFi Cloud Gateway Ultra.

Create a service account in the controller

In this section, you will create a service account in your Ubiquiti UniFi controller, which you will later use in the portnox-unifi-agent Docker container configuration.

Note:

A separate service account is optional but highly recommended for security reasons. If you prefer not to create a new service account, you can use your existing local UniFi administrator credentials instead.

In the UniFi Web UI, go to Settings > Admins & Users > Create New Admin.
Create a service account for UniFi Captive Portal integrations:
1. Activate the Restrict to Local Access Only checkbox.
2. In the Username and Password fields, enter a username and a password for this service account.
3. Deactivate the Use a Predefined Role checkbox.
4. In the Network field, select the Site Admin option.
5. In the Control Plane field, select the None option.
6. Click on the Create button.
In the UniFi Web UI, go to Settings > System > Advanced and deactivate the Sync Local Admins with SSO checkbox if it’s activated.

Note:
This option may be unavailable in some controllers. If it’s unavailable, skip this step.

Set up the Docker container

In this section, you will run the portnox-unifi-agent Docker container using parameters copied from Portnox Cloud and credentials for your UniFi controller.

Install Docker on a local machine (physical or virtual) in the same subnet as your UniFi controller.
For information about installing Docker, see our guides for using Docker with Portnox local RADIUS servers: Install Docker for Linux or Install Docker Desktop for Windows.

Run the Docker container by typing the following command in a shell or command line:

docker run -d --name portnox-unifi-agent --restart=on-failure --pull always \
-e UNIFI_HOST=local IP of your UniFi controller \
-e UNIFI_PORT=your UniFi port, usually 443 or 8443 \
-e UNIFI_LOGIN=the UniFi service account or administrator login \ 
-e UNIFI_PASSWORD=the password for the UniFi service account or administrator\
-e PORTNOX_ECP_ID=the value of Captive Portal ID \
-e PORTNOX_ACCESS_TOKEN=the value of the API access token \
-e UNIFI_SITE=name of your UniFi site (optional) \
-e IGNORE_TLS_ERRORS=true (optional) \
portnox/portnox-unifi-agent:latest

Note:

The UNIFI_SITE optional parameter is used when you have more than one site, and the IGNORE_TLS_ERRORS optional parameter is used when running the UniFi Network Server with a self-signed certificate.

Note:

If you’re using Docker with Windows, replace the \ characters at the end of each line with ^ characters or remove the \ characters and paste the entire command as a single line.

For example:

docker run -d --name portnox-unifi-agent --restart=on-failure --pull always \
-e UNIFI_HOST=192.168.0.1 \
-e UNIFI_PORT=443 \
-e UNIFI_LOGIN=service \
-e UNIFI_PASSWORD=hsDkjFg643mvi!eBHJps \
-e PORTNOX_ECP_ID=b2973887-1274-45c4-91d0-4a342a861c76-homeworld \
-e PORTNOX_ACCESS_TOKEN=HyDd3gwcz3EGXvEEmjes1kktPXY \
-e UNIFI_SITE="default" \
-e IGNORE_TLS_ERRORS=true \
portnox/portnox-unifi-agent:latest

Optional: Check your Docker logs to see if your container started successfully.

Note:

To automatically update the Docker container, install the portnox-autoupdate Docker container as instructed in the following topic: Automatic updates for all Docker containers.

Create a guest network SSID

In this section, you will use the UniFi web UI to create an SSID for your guest network.

In the UniFi Web UI, go to Settings > WiFi > Create New.
In the new WiFi pane:
1. In the Name field, enter the SSID of your guest network.
2. In the Advanced field, click on the Manual option.
3. In the Hotspot 2.0 field, select the Captive Portal option.
4. In the Security Protocol field, select the Open option.
5. Configure remaining fields as required for your network configuration, and then click on the Add WiFi Network button.

Set up the UniFi captive portal

In this section, you will configure the UniFi Captive Portal to work with Portnox Cloud via the portnox-unifi-agent Docker container.

In the UniFi Web UI, go to Insights > Hotspot.
Click on the Landing Page button.
In the right-hand side pane, click on the Authentication tab, and then activate the External Portal Server checkbox.
Click on the Edit link in the External Portal Server field, and in the External Portal Server windows, enter the following IP address: 134.33.139.160 (US) or 50.85.37.114 (EU), and then click on the Save button to close the window.
In the Settings tab:
1. In the Landing Page Settings section, activate the Show Landing Page, HTTPs Redirection Support, Secure Portal and Domain checkboxes, and in the Domain field, paste the value of the Captive Portal Proxy URL (for UniFi) field from Portnox Cloud, and remove the https:// from the start of this value.
2. In the Authorization Access section, in the Pre-Authorization Allowances fields, add the following values: proxy.guests.portnox.com, 134.33.139.160, and 50.85.37.114. In the Post-Authorization Restrictions fields, add the following values (if not present already): 192.168.0.0/16, 172.16.0.0/12, and 10.0.0.0/8.
  
  Note:
  Click on the Add Hostname, IP or Subnet link to add more fields if necessary.
3. Click on the Save button to save your configuration.