Describes how to install a custom Certificate SSL on your Ubiquiti Controller to avoid HTTPS warnings
Install the SSL on Unifi Controller (Ubiquiti) :
Official documentation for UniFi controller describes one way to install the SSL. This method is relatively simple, although there is a common issue related to it where the error message does not indicate the root. This guide describes various alternative installation methods, how to fix these common errors, and provides useful security enhancement tips.
Important note on how to install SSL on Unifi CloudKey:
When installing SSL on Unifi CloudKey, a default server certificate is sometimes used instead of the installed one, which may cause security warnings in the browser. To avoid this situation, please complete the below steps:
-
Connect to the UniFi Cloud Key
-
Stop UniFi Controller by running:
service unifi stop
-
Remove the symbolic link to the default certificate file and copy the real certificate file via:
rm /usr/lib/unifi/data/keystore && cp /etc/ssl/private/unifi.keystore.jks /usr/lib/unifi/data/keystore
-
Comment out or remove the following line in
/etc/default/unifi
UNIFI_SSL_KEYSTORE=/etc/ssl/private/unifi.keystore.jks
-
Restart UniFI Controller using this command:
service unifi start
-
After this, please go ahead with the SSL setup.
The standard method with ace.jar:
The certificate should be installed in the folder where the CSR code was generated. Follow the steps below to complete the SSL installation using ace.jar:
-
Connect to your server through the command prompt.
-
Important: Make sure you start the application with administrator rights on Windows. To do this, right-click the program icon and choose Run as administrator option or do it this way:
Properties Compatibility mark the Run this program as an administrator OK.
On Linux/MacOS, you should have
root
orsudo
user access. For this, you can run the following command on the Linux-based system:sudo su -
-
Go to the UniFi controller main folder by running:
-
cd *Unifi base folder*
The
*Unifi base folder*
needs to be replaced with the following:-
On Debian, Ubuntu, UniFi Cloud Key, and Debian-based Linux:
/usr/lib/unifi/
-
On CentOS, RedHat, Fedora, and other RHEL Linux:
/opt/unifi/
-
On MacOS:
~/Library/Application Support/UniFi
-
On Windows:
"%USERPROFILE%/Ubiquiti Unifi"
or"C:\Users\*account username*\Ubiquiti UniFi"
-
-
Upload the security certificate file in PEM format (.crt file received from the Certificate Authority), root certificate, and intermediate certificates from the received archive in the UniFi base folder. For the standard Domain Validation type SSL, the command will be:
-
java -jar lib/ace.jar import_cert *your certificate*.crt SectigoRSADomainValidationSecureServerCA.crt USERTrustRSAAddTrustCA.crt addtrustexternalcaroot.crt
Note:
*your certificate*
should be replaced with your actual file name. UniFi will ask to enter the keystore password (aircontrolenterprise
unless it was changed in your UniFi settings) and confirm the certificate’s import.Tip: Add
sudo
at the beginning of the command on Linux/MacOS if you are not logged in as root. -
Restart the UniFi controller to apply the changes:
-
service unifi restart
On Windows, close the UniFi application and start it again using the application icon.
If UniFi is configured as a Windows service, you can do this with the following commands:net stop "UniFi Controller"
net start "UniFi Controller"
The restart process may take a bit of time, depending on your machine and the number of applications running. And now you’re done!
Important: There is a known bug on some of the most common modern UniFi versions: after importing the files on the server, an error
“Unable to import the certificate into keystore”
appears.The issue is related to the fact that
ace.jar
on these UniFi versions cannot parse the new string(\n)
symbol.On Linux and MacOS, this issue can be resolved by removing such symbols with a simple command:
tr -d '\n\r' <*file name*="name*"> *temporary file name* && mv *temporary file name* *file name*</*file>
Replace the
*file name*
with the full name of the required file. Apply the command to your certificate, to each of the intermediate certificates, and the root certificate.The
*temporary file name*
is required as a temporary file because the command does not allow it to save the modified content in the same file directly. Therefore it’s required to save it temporarily and then replace the old one with it.Alternatively, you can use this command:
tr -d '\n\r' <*file name*="name*" |="|" echo="echo" $(cat="$(cat" -)="-)"> *file name*</*file>
On Windows, the certificate files can be fixed using Notepad++:
-
Open the file with a text editor.
-
Click
ctrl+F
and go to the tab Replace. -
Mark the option Extended to be able to replace the service symbols.
-
Type
\n
in the form and click Replace All. -
Repeat the same with the parameter
\r
. -
Save the file.
-
Installation with keytool (for Linux and MacOS)
This option is the most reliable since it’s relatively simple, does not have parsing issues, and allows for some flexibility. The import process with a keytool is very similar to the installation on the Tomcat server.
Importing PKCS7
The simplest option is to import the file in PKCS#7 format (.p7b or .cer extension) inside the keystore.
Steps 1-2 are described above.
The Private key for the certificate should be saved in the default UniFi keystore in the file /data/keystore
after the CSR generation.
3. Upload the security certificate file in PKCS#7 format from the received archive in the UniFi base folder.
4. To import the uploaded file into the keystore, run:
keytool -import -trustcacerts -alias unifi -file *your certificate*.p7b -keystore /data/keystore
Enter the keystore password aircontrolenterprise
(unless it was changed in your UniFi settings) and press Enter to complete the import.
5. Restart the UniFi controller to apply the changes:
service unifi restart
And now you’re done!
Warning: You may receive the error “Input not an X.509 certificate”
while importing the SSL in PKCS#7 format. It may be related to the extra empty strings in the file or other formatting issues. If editing the file in a text editor does not help, importing the SSL as PEM files is best.
On Windows, it’s also possible to use this solution:
-
Change the certificate file extension to .cer.
-
Right-click on the file and choose Install certificate. Keep clicking through the options until you locate the Finish button.
TIP: Within the Internet Explorer browser, click on Tools Internet Options to install it. -
Open Content tab and click on Certificates.
-
Choose your certificate out of the Other tab and click Export.
-
Click Next.
-
Select the bullet: “Cryptographic Message Syntax Standard - PKCS#7 Certificates (.P7B)” and check the “Include all certificates in the certification path if possible” box.
-
Click Next Browse. Enter the file name and path for the new combined file to be saved.
TIP: You can save the file with a .cer extension. -
Click Next and then Finish.
-
Use this newly-created file during the installation in the keystore.
Importing PEM
Alternatively, you can import the SSL file in PEM format (.crt). The example below is for the standard Domain Validation certificate:
-
Import the root certificate:
keytool -import -trustcacerts -alias root -file addtrustexternalcaroot.crt -keystore /data/keystore
-
Import intermediate certificates one by one using separate aliases:
keytool -import -trustcacerts -alias intermediate2 -file USERTrustRSAAddTrustCA.crt -keystore /data/keystore
keytool -import -trustcacerts -alias intermediate1 -file SectigoRSADomainValidationSecureServerCA.crt -keystore /data/keystore
-
Import the actual certificate with the alias
unifi
:keytool -import -trustcacerts -alias unifi -file *your certificate*.crt -keystore /data/keystore
PLEASE NOTE: You will need to enter the keystore password for each import and press Enter to complete the process.
TIP: To avoid this, add the argument-storepass *password*
at the end of the command. Replace the*password*
with your actual password for the UniFi keystore. -
Restart the UniFi controller to apply the changes:
service unifi restart
The files are the same as for the Standard installation method with ace.jar.
Installation with keytool (for Windows)
In general, the process is the same as it is on Linux. There is one component that should be taken into account, though. Windows requires the full path to be specified if you are running an application or need to access the file not located in the same folder where you run the command.
The PKCS#7 import command will look like this:
“*Java base folder*\bin\keytool.exe” -import -trustcacerts -alias unifi -file *your certificate*.p7b -keystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore”
*Java base folder*
is specified during the Java installation on server. By default, it is something like “C:\Program Files\Java\*Java version*\”.
Alternatively, run the command below to switch to the Java base folder
:
cd *Java base folder*
and then:
keytool -import -trustcacerts -alias unifi -file “C:\Users\*account username*\Ubiquiti UniFi\*your certificate*.p7b” -keystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore”
Close the UniFi application and start
it again using the application icon.
If UniFi is configured as Windows service, you can do this with commands:
net stop "UniFi Controller"
net start "UniFi Controller"
Import for PEM certificates can be done as described above, specifying the full path to the files in all commands.
PFX file import using Keystore Explorer
The easiest way is to import the PFX on UniFi on Windows is with the help of “Keystore Explorer” (it can be used for Linux/Mac OS also, though, it is best suited for Windows).
-
Open the current keystore file in Keystore Explorer using the default password
aircontrolenterprise
or the one used by the controller.
TIP: You can open thesystem.properties
file and add your custom password in it:app.keystore.pass=*password*
The file is located in the in thedata
subfolder of UniFi base folder. -
Generate the PFX file using any method described here or any online tool (e.g. this converter).
Choose your own password for this. It can be different from the password used in the UniFi controller. -
Switch back to Keystore Explorer and delete the
unifi
entry. -
Click: Tools Import Key Pair PKCS12.
Locate your PFX file and use the password you set during its creation. -
The Key Pair Entry Alias should be set as
unifi
. -
Provide the new password. It should be the keystore password (
aircontrolenterprise
unless it was changed in your UniFi settings). -
Save the keystore file using File Save (or simply click on the related icon).
-
Restart the controller to apply the changes.
On Linux:service unifi restart
On Windows, close the UniFi application and start it again using the application icon or, if UniFi is configured as a Windows service, with commands:net stop "UniFi Controller"
net start "UniFi Controller"
WARNING: Sometimes, keystore may got corrupted because of multiple imports. If the process does not work properly, delete the initial keystore file and restart UniFi to create a new one, and only after this proceed with the PFX import.
PFX file import (Linux and MacOS) via command line
This option can be used if the Certificate Signing Request (CSR) was generated elsewhere or the OpenSSL was used during the process instead of default UniFi tool.
In such a case, a private key (.key) is created separately. It’s required to import the key file into the keystore
along with the certificate (.crt) and chain (.ca-bundle) files.
Steps 1-2 are the same as above.
If you prefer doing all process through the command line:
3. Upload the PEM security certificate file (.crt), and chain file (.ca-bundle) received in an archive from the Certificate Authority into the UniFi base folder. For your convenience, move or upload the previously generated private key file in the same folder.
Technically, you can put them in different folders; however, in such a case, make sure to add the full path to the files in the command.
4. Generate the PKCS#12 (PFX) file using the similar OpenSSL command:
openssl pkcs12 -export -out *your certificate*.pfx -inkey *your certificate*.key -in *your certificate*.crt -certfile *your certificate*.ca-bundle -name "unifi"
5. Import the created PFX file into the keystore:
keytool -importkeystore -srckeystore *your certificate*.pfx -srcstoretype PKCS12 -destkeystore /data/keystore -deststoretype jks -deststorepass *password*
Replace the *password* with your actual password for the UniFi keystore.
6. Restart the UniFi controller to apply the changes:
service unifi restart
If you prefer generating the PFX elsewhere (e.g. this converter):
3. Generate the PKCS#12 (PFX) file using any convenient tool.
4. Upload the PFX file on the server where UniFi controller is installed (in the UniFi base folder).
5. Import the created PFX file into the keystore:
keytool -importkeystore -srckeystore *your certificate*.pfx -srcstoretype pkcs12 -srcalias 1 -destkeystore /data/keystore -deststoretype jks -destalias unifi -deststorepass *password*
6. Restart the UniFi controller to apply the changes:
service unifi restart
PLEASE NOTE: For the PFX file without an alias assigned, 1 is used as the default alias. Ensure you specify the -srcalias
and -destalias
to avoid an error “Alias unifi does not exist”
. Replace the *password*
with your actual password for the UniFi keystore.
There is a small chance that default alias is different. If you face an error with it, you can check the alias with any of the following commands:
openssl pkcs12 -in *your certificate*.pfx -info
keytool -list -storetype pkcs12 -keystore *your certificate*.pfx -v
PFX file import (Windows) via command line
The process is similar to the installation on Linux. The PFX file can be generated this way:
-
Save the certificate and the private key files in one folder using the same file names and corresponding extensions: example.p7b, example.key. Run the command in
cmd
or PowerShell:certutil -mergepfx *your certificate*.p7b *your certificate*.pfx
Alternatively, you can put the certificate, private key and CA-bundle in one folder and generate it with OpenSSL:*OpenSSL path* pkcs12 -export -out *your certificate*.pfx -inkey *your certificate*.key -in *your certificate*.crt -certfile *your certificate*.ca-bundle -name "unifi"
Default OpenSSL path on Windows (if you have it installed) is“C:\*OpenSSL version*\bin\OpenSSL.exe”
. -
Import the created PFX file into the keystore:
“*Java base folder*\bin\keytool.exe” -importkeystore -srckeystore *your certificate*.pfx -srcstoretype pkcs12 -srcalias 1 -destkeystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore” -deststoretype jks -destalias unifi -deststorepass *password*
*Java base folder*
is specified during the Java installation on server. By default, it is something like“C:\Program Files\Java\*Java version*\”
. -
Close the UniFi application and start it again using the application icon or, if UniFi is configured as a Windows service, with the commands:
net stop "UniFi Controller"
net start "UniFi Controller"
Unify SSL security features
Here we list some features not directly related to the SSL setup, although they’re related to site security and different ways to configure them.
-
The ECC certificates won’t work even though the files can be successfully imported on the server.
-
Server Name Indication (SNI) is not supported.
-
HTTPS redirect is enabled on newer versions of UniFi by default. Access the UniFi admin panel using the http:// link (by default,
*hostname*:8080
insystem.properties
) then, if the SSL is already installed on UniFi, you’ll be forwarded to the https:// link (by default,https://*hostname*:8443
).
This option works on all UniFi versions starting4.x
. -
HSTS can be enabled on UniFi in the
system.properties
file by modifying these parameters:unifi.https.hsts=false
- set to true to enable HSTSunifi.https.hsts.max_age=*value*
- you can specify the duration for how long HSTS is cached (in seconds)unifi.https.hsts.preload=false
— set to true only if you do not plan to remove the HSTS, as it will add your UniFi hostname to the preload list, deletion from which should be requested specificallyunifi.https.hsts.subdomain=false
- set to true if you would like to apply HSTS policy for subdomains of your domain name, as well as for the main domain name
Uncomment the corresponding (above-mentioned) strings, save the file, and restart the UniFi to complete the process. -
Allowed cipher suites and SSL/TLS versions can be enabled on UniFi in the system.properties file using the following parameters:
unifi.https.ciphers=cipher1, cipher2, etc.
- replace the values with the actual cipher names you want to enableunifi.https.sslEnabledProtocols=protocol1, protocol2, etc.
- replace the values with the actual protocol names you want to enable
Uncomment the corresponding (above-mentioned) strings, save the file and restart the UniFi to complete the process.
The optimal configurations for UniFi can be checked here.