×

UNMS - Security

Overview

Readers will learn more about the various UNMS security features such as certificates, encryption and credential management. 

NOTES & REQUIREMENTS:
  • More information on the Ubiquiti Network Management System can be found on the UNMS website.
  • Join the UNMS discussion on the Ubiquiti Community and interact with other experts that are active on forum.

Table of Contents

  1. Introduction
  2. UNMS Server Ports, Certificates and HTTP Headers
  3. Device Discovery and Connection
  4. UNMS Login
  5. Data Storage
  6. Credentials Vault
  7. Related Articles

Introduction

Back to Top

The security of the UNMS server and its users is one of the main design principles during the UNMS development process. UNMS uses double encryption for critical elements such as device communication, and will not store credentials unless strictly needed. A special bounty program was also created to help find any security issues in order to patch them as soon as possible.

UNMS Server Ports, Certificates and HTTP Headers

Back to Top

UNMS Server Ports and Certificates

UNMS will only communicate through encrypted channels (HTTPS and WSS), with one exception: HTTP port 80 is used by UNMS exclusively for generating the built-in Let's Encrypt certificate. There is no easy way around it since Let's Encrypt servers need to access TCP port 80 in order to validate that the certified domain really belongs to the machine generating the certificate. UNMS strictly controls whether the cipher suites are enabled or not. We do not support the DNS challenge since it is almost impossible to create a simple user-friendly user interface and set it up for all DNS hosting.

NOTE: If the native Let's Encrypt certificate is used, then UNMS has an A+ mark in the SSL Labs security test.

If users supply their own certificate during UNMS installation then port 80 is not used at all and can be completely closed. However, it is important to mention that there is a significant benefit of using the native Let's Encrypt certificate. With this setup, the user does not need to worry about the certificate's expiration date as UNMS will refresh the certificate automatically.

All other communication for HTTP (80) is automatically redirected to HTTPS (443) in order to utilize security encryption of the HTTPS protocol. This applies to any custom HTTP(S) ports set as well. Due to the redirection, the UNMS user interface, API and WebSocket cannot be accessed via HTTP.

It is also possible to set up a custom inform port in order to separate the UNMS GUI from the communication channel to devices. The inform port is used by the devices to connect to the UNMS server and is set to TCP port 443 by default. Separating the inform port from the GUI port will allow you to access the UNMS GUI exclusively through a private network, while still allowing devices to communicate with it. 

NOTE: See the Optional Installation Steps article for more information on how to change the inform port.

UNMS HTTP Headers

HTTP headers are important for UNMS security because they control several different browser options such as the location where the JavaScript is downloaded from, how it should run, and how certificates should be approached. 

NOTE: UNMS uses the Security Headers platform to evaluate the security efficiency of its HTTP headers and currently holds an A mark.

Device Discovery and Connection

Back to Top

Generic UNMS Key

The most secure way to connect a device to UNMS is to manually add the generic UNMS Key to the device. This key contains the URL address of the UNMS server and a generic AES encryption key. The device will use to key to connect to the UNMS server using the encrypted WebSocket protocol (WSS). All devices connecting to UNMS, will use both WSS and AES encryption, ensuring a double encrypted connection. All communication occurs through this secured channel, including the UNMS Terminal  terminal.png  that provides remote shell access, but does not use SSH to accomplish this.

UNMS Untrusted Certificates

Another scenario where the double encryption is important is when the UNMS server does not have a verified (valid) certificate and is accessible only through an IP address. Besides SSL, UNMS will use another encryption system (AES 256 GCM) to ensure a system that is resilient to MITM attacks even when the certificate is not trusted. 

NOTE: See the The UNMS Key and the Device Registration Process article for more information on the UNMS key and its encryption.

Remote Discovery

Manually inserting generic UNMS keys into devices one by one is not practical, so UNMS also allows you to add devices using the (remote) Discovery feature. This feature will automatically discover devices in a (remote) network and can automatically insert the generic UNMS key after providing the device credentials.

NOTE: See the Remote Discovery article for more information on the Remote Discovery feature.

This is one of only two occasions (the other one being the UNMS Terminal) when UNMS will ask for the credentials of a device uses them to connect via SSH or HTTPS. For security reasons, UNMS discovery will not allow a device to connect if HTTPS is not enabled. The credentials are not saved during this process. After the initial connection is established UNMS inserts the key into the device and a new encrypted WebSocket is established for further communication. In summary, the initial connection is made by UNMS , but the communication is then initiated by the device and UNMS assumes the role of the WebSocket server.

UNMS Login

Back to Top

UNMS Login Token 

The security of the UNMS user login process is based on a token that is sent through the A-Auth-Token header. This token also serves as a protection against CSRF attacks. On older UNMS releases, the user session timeout was fixed at 24 hours and extended in case of user activity. On newever versions, the timeout is can be customized (from 30 min up to 30 days) in the  settings.png  Settings  > Users > Edit Account section. While a user is active the token's validity is extended for up to one month , after which it is necessary to log in again. There is a brute force protection build in UNMS. UNMS uses the hapi-rate-limit library with the following set of options:

options: {
          enabled: false,
          checkUnauthorized: true,
          pathLimit: false,
          userPathLimit: true,
          userCache: { expiresIn: config.apiRateLimit.userCacheExpiresIn },
        },
NOTE: The value of userCacheExpiresIn is set to 2 minutes.

UNMS User Roles

Currently, UNMS supports two different user roles. The Admin role has full access to all features, whereas the Read-Only role cannot make any changes to the network or devices. You can specify a user as Read-Only in the   settings.png  Settings  > Users section.

UNMS Two-Factor Authentication

UNMS supports Two-Factor Authentication (2FA) using the Google Authenticator app. There are 2FA applications for desktop computers available as well, but they are not recommended as 2FA is most useful if it is placed on a completely separated device. When 2FA is set up, the user will need to log in to UNMS with their credentials and insert a 6 digit security code provided by the Authenticator app. Even if somehow the user's UNMS credentials were compromised, the possible intruder would also need access to the associated mobile phone in order to access the UNMS account.

Follow the steps below to enable Two-Factor Authentication (2FA) for a UNMS user account:

1. On a mobile device, download the Google Authenticator app for iOS or Android

GUI: Access the UNMS Controller Web Portal.

2. Navigate to the  settings.png  Settings  > Users > Edit Account section and select Enable Two Factor.

3. From the app, select Add Account (+) and scan the provided QR code. 

NOTE: It is also possible to manually enter the code if you are unable to scan it. See the Password Recovery article if you are encountering any issues with 2FA and want to disable the feature.

Data Storage

Back to Top

The login credentials of UNMS users are stored and protected with bcrypt. Plaintext is never used to save user passwords anywhere in UNMS. UNMS can also store device credentials in the Credentials Vault, see the section below.

Credentials Vault

Back to Top

The UNMS Credentials Vault feature is available starting from the v0.14.0 release and allows you to securely store device credentials. Since the v1.1.0 of UNMS there is also an option to generate credentials for many devices at once through the Vault which makes it a key component of the UNMS security. The vault encrypts stored passwords with asymmetric encryption. A public key is used to write data and a private key, protected by a master password, is used to read them. The master password is generated automatically during the vault creation process.

It is currently necessary to store the Vault key file somewhere safe, but also readily available in order to unlock the Vault. The Vault key needs to be re-inserted every time the UNMS server is restarted. The UNMS Vault can be managed through the  settings.png  Settings  > Credentials Vault section.

Related Articles

Back to Top

UNMS - The UNMS Key and the Device Registration Process

UNMS - Password Recovery

Ubiquiti's Guide to Basic Security

Was this article helpful?
3 out of 3 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community
Can't find what you're looking for?