Configuring Ubiquiti with USG

This chapter describes how to configure Ubiquiti with USG, version equal to or greater than 5.12.66.
Before proceeding further with the configuration, you need to configure HSNM with a domain and a gateway as described in Adding a New Gateway.

Prerequisites

The prerequisites required for configuration are:

Gateway USG configured with connected public WAN and private LAN
Ubiquiti controller version> = 5.12.66 installed on PC / Mac connected to the private LAN
AP Unifi connected to the private LAN network of the USG
HSNM version >= 7.0.142
Port forward (step 4) from WAN to private LAN for RADIUS answers
HSNM gateway configured with Ubiquiti hardware type

When you set the Secret Radius in your %DEVICE” do not exceed 12 digits code and do not use symbols, otherwise UniFi will not send it correctly.

Now inside HSNM, select your Gateway, click the dropdown menu, choose Edit.
Expand the General Data session.
In the Hardware Type field, choose Ubiquiti.

Step 1

Now inside HSNM, select your Gateway, click the dropdown menu, choose Edit.

Step 2

Expand the General Data session.

Step 3

In the Hardware Type field, choose Ubiquiti.

Wireless Network

Step 1

Login to your Unifi controller and click the Settings icon on the bottom left.
On the left menu, scroll down to Wireless Networks and click Create New Wireless Network.

Configure with:

Name/SSID–Edit the name for your network
Enabled–Tick Enable this wireless network
Security–Select Open
Guest Policy–Tick Apply guest policies

Step 2

Optional: expand the Advanced Options session and select the User Group (traffic shaping) that you will configure in the “User Group (Option)” paragraph.

Step 3

Once completed, click the Save button to save the entry.

Radius Profile

Step 1

On the left menu, select Profiles and create the Radius profile.
In the Radius Profile header, enter the details as follows:

Profile Name–Edit the name for your profile
VLAN Support–Tick Enable RADIUS assigned VLAN and tick Enable RADIUS assigned VLAN for wireless network
RADIUS Auth Server–Edit the Port and insert the Secret
Accountings–Tick Enable accounting
Interim Update–Tick Enable Interim Update (see note above)
Interim Update Interval–Edit the time
RADIUS Accounting Server–Edit the Port and insert the Secret

In the IP Address fields enter the public IPs of the Radius server of your HSNM Radius and its relevant Secret.
In order to add the Secret you need to get it from your HSNM as described in the Radius Secret paragraph.

Troubleshoot: Interim Update

It will use the value you edit here and not the value you enter in the Product Policy. This value must be equal to or lower than the value entered in the products you set up for the users.

Ubiquiti UniFi Controller does not support or has errors in accounting radius. The data is correct only if the system is able to reach the UniFi controller (normally with NAT or VPN rules) and compensate directly for failings. If not possible, we recommend you to use this type of gateway only to authenticate users. You cannot parametize the user data rate in the Products, you can define it only in the controller.

Guest Policies and Portal Customisation

Step 1

Now, you need to set up the guest policies. From the Settings menu on the left, open the Guest Control page.
In the Guest Policies header, enter the details as follows:

Guest Portal–Tick Enable Guest Portal
Authentication–Select Hotspot
Landing Page–Select Redirect to the original URL

Once you have completed the above steps, in the Portal Customisation header, enter the details as follows:

Template Engine–Select Angular JS
Override Default Template–Tick Override templates with custom changes
Title–Edit the title for your welcome portal

Ignore any update message about portal customization.

Radius Authentication and Access Control

Now in the same page, the next step is to set up the Radius authentication and access control.

Step 1

In the Hotspot header, tick Enable RADIUS base authorisation

Step 2

In the Radius header, enter the details as follows:

Profile–Choose the profile you have previously edited in the “Radius Profile” paragraph
Authentication Type–Select CHAP
Disconnect Request–Tick Accept incoming disconnect request
Receiver Port–Edit a port that should be the same as in the “Downloading the Configuration Files” Step 5 (including HSNM) and prerequisites (for forwarding)

Step 3

In the Access Control header, in the Pre-Authorization Access fields configure with:

The public or private IP class of your HSNM and in addition any FQDN that points to it
The network class of the private LAN
Optional: in the Post-Authorization Restrictions fields, you need to add the network class of the USG WAN, so guests cannot access your public network.

In the access control section, always enter IPs with CIDR notation even for individual IPs (e.g. 1.1.1.1/32).

Step 4

Upon completion of the above steps, click the Apply Changes button to finish.

User Group (Option)

Now you have the ability to limit the bandwidth assigned to the guests, by creating a User Group.

Step 1

On the left menu, scroll down to User Group and click Create New User Group.

Step 2

Configure with Name, Bandwidth Limit (Download), Bandwidth Limit (Upload)

Step 3

Upon completion of the above steps, click the Save button to finish.

It will take into account the speed you set up here and not the one of the Product Policy in your HSNM.

Configure with:

Name/SSID–Edit the name for your network
Enabled–Tick Enable this wireless network
Security–Select Open
Guest Policy–Tick Enable accounting
Interim Update–Tick Apply guest policies

Step 4

Now you need to apply the User Group to your network. On the left menu, scroll down to Wireless Networks and select your Wireless Network.

Step 5

Expand the Advanced Options section and select the User Group you have just created.

Downloading the Configuration Files

Step 1

Now access your HSNM and select your gateway. In the Hardware Type section, select Ubiquiti UniFi Controller

Step 2

From the context menu of the gateway, press Download Gateway Config Files to download the configuration zip file.

Step 3

Once the zip file is unpacked, you will find the following files:

authorize.html
index.html

Step 4

The files must be edited in the Ubiquiti Themes folder. The paths vary depending on the SO where the Ubiquiti Controller is installed:

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/data/sites/default/app-unifi-hotspot-portal
For some Linux installation path will be: /opt/unifi/data/sites/default/app-unifi-hotspot-portal
CloudKey: /srv/unifi/data/sites/default/app-unifi-hotspot-portal

For some Linux distributions, path may differ:
/opt/UniFi/data
/var/opt/UniFi/data

You don’t need to edit the MAC address of the gateway in your HSNM.

Step 5

In your firewall, configure the port forward to accept disconnection requests from your HSNM (the same as in the “Radius Authentication and Access Control” paragraph and prerequisites).

You need to create the rule must with the following characteristics:

enable it
limit it to the public IP of your HSNM (optional but we suggest it for security reason)
the port must be the same set up in the “Radius Authentication and Access Control” paragraph and chosen in the prerequisites
address it to the LAN IP address of the Unifi controller
select the UDP protocol
afterwards in your HSNM > gateway. configure the Radius section as follows

If your Unifi controller is behind a nat or a firewall, you need to enable the port forward of the port previously chosen in the “Radius Authentication and Access Control” paragraph toward the IP of the USG WAN (the same as in the prerequisites).

Step 6

For Ubiquiti-type gateways, you need to enable these settings for the reasons listed below:

Force disconnections: if enabled, connections that have not received updates from the gateway for the ‘Interim Update’ time defined in the Product Policy plus the Timeout for Idle’ value are automatically closed.

Send disconnections requests to the gateway: in addition to forcing disconnections, it also sends a radius disconnection request to the gateway. Some types of gateways (e.g. Ubiquiti) may not send the stop to the radius and consider the device always active. If enabled, the gateway has to be reachable for the UDP port indicated in the “Radius Authentication and Access Control” paragraph.
Port for disconnection requests: port used by the gateway to accept disconnection requests. It is usually the 3799 but can vary depending on the type of gateway. It is the same one configured in the “Radius Authentication and Access Control” paragraph and opened in the firewall at the beginning of Step 5 in the “Downloading the Configuration Files” paragraph.
Check consumption by users: If the gateway does not support all the necessary radius attributes and the appliance is able to send disconnection requests (points listed above), it periodically checks the consumption of the logged-in users and if time/traffic limits are reached or at expiration, disconnects the user.

HTTPS Fullchain

In case you need to configure the access over HTTPS, you need to follow the steps below:

Step 1

Decide which FQDN to dedicate to the Unifi controller (in our test unifi.http://hsnm1.hsnetworkmanager.com.com)

Step 2

Purchase a valid certificate (in our case wildcard certificate .http://hsnm1.hsnetworkmanager.com.com)

Step 3

Make sure that you have the complete chain (cert, intermediate, root) of your own certificate because UNIFI controller requires it. If you already have the full chain, then skip to the HTTPS keystore section otherwise continue in this section.

Step 4

Purchase a valid certificate (in our case wildcard certificate .HSNM.com)

Step 5

If the full chain is not available, you can use the following online utility: https://tools.keycdn.com/ssl to trace the correct concatenation.

In our test we initially had the CRT and CA-intermediate and not the root. (You can deduct it that in the form we have pasted only 2 —–BEGIN CERTIFICATE—– —–END CERTIFICATE—–).
After a small search we went back to the missing root certificate (in the previous box identified by ISSUER CN):

and the root cerfiticate in our case, is available at the issuer’s official website:
https://knowledge.digicert.com/generalinformation/INFO4033.html#links

Beware, this may vary depending on the issuer you choose for the certificate.

Once we have the entire chain available, repeat the verification on the site https://tools.keycdn.com/ssl to make sure that the complete chain is now correct.
(This time the —–BEGIN CERTIFICATE—– —–END CERTIFICATE—– should be 3)
We should be in this final situation:

With a text or cli editor, we put certificate-intermediate-root into a single file, in the order in which we tested it in the online tool.
In our case we will name the final file as fullcert.crt

HTTPS Keystore

Step 1

Install the following software https://keystore-explorer.org/downloads.html

Step 2

Create a new JKS-type keystore

Step 3

Click on Tools > Import Key Pair

Step 4

Select the certificate format (in our case we used PKCS #8)

Step 5

Select the key and the concatenated fullcert you created earlier

Step 6

Uncheck Encrypted Private Key if you don’t have any type of passphrase set for the certificate, or type the Decryption Password of your certificate

Step 7

Click Import and choose Unifi as alias

Step 8

Set as password aircontrolenterprise and as key pair and re-insert it for confirmation

Step 9

Click on File > Save as

Step 10

Set the keystore password aircontrolenterprise

Step 11

Upload the new file created in the Unifi folder by replacing the existing “keystore” file.
The path of the file depends on the SO version where the UniFi controller is installed.

Step 12

Restart ace.jar or the controller directly in case, for example, it is installed in a WINDOWS environment.

Step 13

Optional: to verify from the front end of the controller that the installation was successful, change the hosts file to point the public IP with which the USGWAN exits, to a valid FQDN for the certificate:
C:\Windows\system32>notepad c:\Windows\System32\drivers\etc\hosts

Step 14

Save the change and through CMD, test the real changes of the host file with the command:
Ping execution unifi.valid-certificate-FQDN.com [IPCONFIG] with 32 bytes of data
Reply from IPCONFIG: byte=32 time=1ms TTL=62
Reply from IPCONFIG: byte=32 time<1ms TTL=62

Configuring the Port Forwarding

In this section, now you need to configure a port forwarding in your WAN firewall and in the Unifi controller to allow the interface to access from outside.

Step 1

Go to the Settings menu, then scroll down to Routing & Firewall and select Port Forwarding. Enter the details as follows:

Name–Edit the name for your port forward rule
Enabled–Tick Enable this port forward rule
From–Select Limited
Port–Enter 8443
Forward IP–Enter 10.0.150.100 (example)
Forward Port–Enter 8443
Protocol–Select TCP

The UC port is the 8443 that, as shown in the below picture, is redirected to the private IP of the Unifi controller with TCP protocol, limited to the connection public IP from which we access.

Step 2

Click Save in the bottom left corner of the page. Your selected entries are saved

At this time, we can invoke via browser the controller from the whitelisted IP. In case the installation of the certificate is successful, you will reach the portal in HTTPS.

If you do not get this point with the certificate correctly installed, you will need to check all the previous points described in the current “HTTPS Keystore” paragraph and the actual routing of ports in the firewalls. If the installation has been successful, the last “optional” part can be removed.

HTTPS Welcome Portal

In this section, you can configure the ability to use the HTTPS protocol.
You need to redirect the 8843 TCP port (default for HTTPS external port) to the controller IP limited to the network class chosen for the private LAN (in our case 10.0.150.1/24).

Step 1

Go to the Settings menu, then scroll down to Routing & Firewall and select Port Forwarding.
Select the options as follows:

Name–Enter the name (e.g. 8843toController)
Enabled–Tick Enable this port forward rule
From–Select Limited and enter the controller IP 10.0.150.1/24
Port–Enter 8843
Forward IP–Enter 10.0.150.100
Forward Port–Enter 8843
Protocol–Select TCP

Step 2

Click Save in the bottom left corner of the page. Your selected entries are saved.

Now you need to configure the Guest Control to use the HTTPS protocol

Step 3

Go to the Settings menu, then scroll down to Guest Control.
Select the options as follows:

Use Secure Portal–Tick it
Redirecting Using Hostname–Set up the same FQDN you tested in the “HTTPS Keystore” paragraph or a valid entry for the certificate you have configured.
Enable HTTPS Redirection–Tick it

Step 4

Once completed, click the Save button

Step 5

Now you need to recover the SSH access password of the devices.
Go to the Settings menu, then scroll down to Site.
Select the options as follows:

DHCP Snooping–Tick Enable DHCP Snooping
Automatically Optimite Network and WiFi performance–Switch ON
SSH Authentication–Tick Enable SSH authentication
Username–Enter the username
Password–Enter the password

Step 6

Use a shell to access via SSH to your own USG and enter the following STATIC DNS:
sudo vi /etc/dnsmasq.d/dnsmasq.static.conf
digit
address=/chosenhostname in the previous point/CONTOLLERIPLANPRIVATE
in our case
address=/unifi.valid-certificate-FQDN.com/10.0.150.100
save the new (:wq) file creted and run
sudo /etc/init.d/dnsmasq force-reload

Execute a ping text to unifi valid-certificate-FQDN.com from the USG.
If the solved IP is the one just edited, you have successfully executed the STATIC DNS.

admin@USG:~$ ping unifi. valid-certificate-FQDN.com
PING unifi (10.0.150.100) 56(84) bytes of data.
64 bytes from unifi (10.0.150.100): icmp_req=1 ttl=128 time=1.19 ms
64 bytes from unifi (10.0.150.100): icmp_req=2 ttl=128 time=0.758 ms

This procedure will become permanent even if the USG is re-provisioned.

Configuring the HTTPS Network

Step 1

Go to the Settings menu, then scroll down to Networks
Enter the details as follows:

Name–Enter the name
Purpose–Select Corporate
Network Group–Select LAN
Gateway/Subnet–Enter the details of your gateway and network IP
Domain Name–Edit as domain name the domain belonging to the FQDN set up in the previous step.
DHCP Mode–Select DHCP Server
DHCP Name Server–Select Auto
DHCP Gateway IP–Select Auto
DHCP Unifi Controller–Enter the IP of your controller

Step 2

Click the Save button that displays at the bottom left of the window.

You can now redirect to the Welcome Portal with a secure HTTPS protocol.