This article describes how to install an issued SSL certificate on Ubiquiti Unifi server. The methods are grouped by the preferred one for each system (though each method can technically be used for each system with some modifications).
- General installation method with ace.jar tool
- SSL Installation options for UniFi on Windows
- SSL Installation options for UniFi on Linux/MacOS
- SSL import using PFX file
- Additional SSL features and tips
Please keep in mind: When installing SSL on Unifi CloudKey, a default SSL (server certificate) might be used instead of the custom one. This may cause some security warnings as a result. Here’s a resolution steps for such cases:
- Connect to UniFi CloudKey.
- Stop Controller using the below command:
service unifi stop
- Clear out the symbolic link to the default SSL file and copy the custom SSL file using the following command:
rm /usr/lib/unifi/data/keystore && cp /etc/ssl/private/unifi.keystore.jks /usr/lib/unifi/data/keystore
- Remove (or comment out) the below line in the
- Restart the Controller using this command:
service unifi start
- Then just proceed with the certificate installation using the corresponding method below.
General installation method with ace.jar tool
This is the only method described in the official documentation for UniFi. The process itself is relatively simple — just add the SSL files to the keystore created along with the CSR code by following these steps:
Step 1. First, connect to the server where the controller is installed with the help of the appropriate command prompt:
- For Linux-based servers, multiple command prompt (SSH) applications exist. The most common one is Putty. There are versions of Putty for each server type, including Linux servers and Windows servers, as well as the multiple analogues for Android.
- For MacOS, use the Terminal application.
- For Windows servers, you can connect via remote desktop and use either cmd or PowerShell.
Important: It is necessary to run all further commands with administrator rights on Windows, or have root or sudo user access on Linux/MacOS.
To run commands with administrator rights on a Windows server, you can right-click the program icon and choose the Run as administrator option, or click Properties -> Compatibility -> Mark the option ‘Run this program as an administrator’ -> confirm (OK).
To set up the required access on Linux-based systems, run sudo su – or just start each command with sudo.
Step 2. Upload the PEM certificate (the .crt file you received from the Certificate Authority), root certificate, and the two intermediate certificates from the downloaded archive on your server. if you received a combined .ca-bundle file instead of separate intermediate and root files, you can open the file with any text editor and save the codes from inside it as separate files.
For any Domain Validation type SSL (like PositiveSSL), the command will look like this:
- for Linux/Mac OS:java -jar /*UniFi root*/lib/ace.jar import_cert /*Some path*/example.crt /*Some path*/SectigoRSADomainValidationSecureServerCA.crt /*Some path*/USERTrustRSAAddTrustCA.crt /*Some path*/addtrustexternalcaroot.crt
- for Windows:java -jar “*UniFi root*\lib\ace.jar import_cert “*Some path*\example.crt” “*Some path*\SectigoRSADomainValidationSecureServerCA.crt” “*Some path*\USERTrustRSAAddTrustCA.crt” “*Some path*\addtrustexternalcaroot.crt”
Note: Replace ‘example.crt’ and ‘Some path…’ with your actual SSL file name and paths to each file. Next, you will need to type in the keystore password (this is aircontrolenterprise, unless it was changed in your UniFi settings) and confirm the certificate’s import.
Important: The root folder name depends on the system UniFi controller is installed on:
- /usr/lib/unifi/ – for UniFi Cloud Key, Ubuntu, and other Debian-based Linux distributions;
- /opt/unifi/ – for CentOS, RedHat, Fedora, and other RHEL Linux distributions;
- ~/Library/Application Support/UniFi – for Mac OS;
- “%USERPROFILE%/Ubiquiti Unifi”
or (which is the same)
“C:\Users\*account username*\Ubiquiti UniFi” – for Windows.
Alternatively, you can open the UniFi root folder first using the command cd *Unifi root*, move all the files there, and then run the installation command in it. By doing it this way you won’t need to specify the full paths in the command itself.
Step 3. Restart the UniFi controller for the changes to apply:
- On Linux/MacOS, this is: service unifi restart.
- On Windows, just close the UniFi application and start it again by clicking on the corresponding icon.
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: Some versions of UniFi may show the error, “Unable to import the certificate into keystore”. This is related to the ace.jar inability to parse the new line symbols (\n and \r) on these particular versions of UniFi.
On Linux and MacOS, you can fix this by simply removing these symbols from each file using the command:
tr -d ‘\n\r’ < * your file name* | echo $(cat -) > *your file name*
Use the name of certificate, intermediate certificate, or root file instead of *your file name*. Apply the command to each file.
On Windows, the certificate files can be fixed using Notepad++:
- Open the file with Notepad++.
- Click ctrl+F and go to the Replace tab.
- Click the Extended option to replace the required symbols.
- Type \n in the “Find what” box and click Replace All.
- Repeat this process using the value \r.
- Save the file.
SSL Installation options for UniFi on Windows (Keystore Explorer)
The easiest way to install an SSL on UniFi on Windows is to use the “Keystore Explorer”. The process is simple:
- For SSL activation choose the option “Auto-activate” as you will create a new keystore anyway.
- Open the current UniFi keystore file in Keystore Explorer using the default password aircontrolenterprise or the one set* for the controller.*Note: The password can be set in the file system.properties in /*UniFi root*/data/ with the following parameter: app.keystore.pass=*password*
- Create the PFX file from the saved Private key file and SSL files. To do this, use this online converter or another similar tool. Alternatively, you can do the following:Put both the certificate and the Private key files in one folder using the same file names and correct extensions.For example, example_com.p7b, example_com.key.Use the following command in cmd or PowerShell to generate the PFX file:certutil -mergepfx example_com.p7b example_com.pfx Note: There is no need to mention the key file as it is fetched by default if the key and the certificate files have the same names and corresponding extensions. You will be asked to enter the new password. Set any password for this.Warning: the certutil command may fail sometimes because of how the files are formatted. If this happens, try using another method.If you have OpenSSL installed, you can do it the same way:
“*OpenSSL path*” pkcs12 -export -out “*Some path*\example.pfx” -inkey “*Some path*\example.key” -in “*Some path*\example.p7b” -name “unifi”
- Go back to Keystore Explorer and delete the unifi entry from your keystore.
- Choose the option: Tools -> Import Key Pair -> PKCS12.Locate your PFX file (example_com.pfx) and import it. Use the same password you set during the PFX creation (step 3).
- For the Key Pair Entry Alias, use unifi.
- Provide the new password. For this, use your default keystore password (this is always aircontrolenterprise, unless you changed it in system.properties).
- Save the modified keystore file with File -> Save (or simply click on the Save icon).
- Close the UniFi application and start it again with the corresponding icon to apply changes.Warning: Sometimes, the keystore may get corrupted due to multiple imports. The solution is to delete the initial keystore and restart UniFi to create a new one. You will be able to do the setup after this.
Note: This tool is also available for Linux/MacOS. However, both systems also have ready-to-use command line options for the process.
SSL Installation options for UniFi on Linux/MacOS
SSL Import using Keytool
This option is quite simple. It doesn’t have parsing issues, and allows for some flexibility. The process itself is similar to the certificate installation on Java-based servers like Tomcat.
Importing PKCS7 file
The most convenient option is to import the file in PKCS#7 format (.p7b or .cer extension) inside the UniFi keystore.
Steps 1-2 are as above.
The Private key for the certificate should be saved in the default UniFi keystore in the file /*UniFi root*/data/keystore after the CSR generation.
3. Upload the certificate file in PKCS#7 format from the received archive on your server.
4. Use the following command to import this file into the keystore:
keytool -import -trustcacerts -alias unifi -file /*Some path*/exmple.p7b -keystore *Unifi root*/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
Alternatively, you can open the UniFi root folder first using the command cd *Unifi root*. Put all the files in the folder and then run the installation command in it. This way you won’t need to specify the full paths in the command itself.
Warning: You may get the error “Input not an X.509 certificate” during the certificate import. It may be related to the extra empty lines in the file or another formatting issue. If editing the file in a text editor doesn’t help, the best solution is to import the certificate as separate PEM files as described in the next section.
Import with PEM files
If importing the PKCS#7 file results in an error, you can use PEM files (.crt) instead. The following are commands for any Domain Validation SSL type (like PositiveSSL):
- Import the root certificate first:keytool -import -trustcacerts -alias root -file /*Some path*/addtrustexternalcaroot.crt -keystore /data/keystore
- Import intermediate certificates one by one, using a separate alias for each:keytool -import -trustcacerts -alias intermediate2 -file /*Some path*/USERTrustRSAAddTrustCA.crt -keystore /data/keystoreandkeytool -import -trustcacerts -alias intermediate1 -file /*Some path*/SectigoRSADomainValidationSecureServerCA.crt -keystore /data/keystore
- Import your certificate file using the alias unifi:keytool -import -trustcacerts -alias unifi -file /*Some path*/example.crt -keystore /data/keystore Note: You will need to enter the keystore password after running each command and press Enter to complete the import.Tip: To avoid entering the password multiple times, add the argument -storepass *password* at the end of each command. Use 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 installation method using ace.jar.
Note: The same method can be used on Windows and the process is very similar. However, it should be noted that Windows requires you to use the full path to the keystore application and each file is imported in Windows format.
Import in PKCS#7 will look like this, for example:
“*Java base folder*\bin\keytool.exe” -import -trustcacerts -alias unifi -file “*some3 path*\example.p7b” -keystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore”
SSL import using PFX file
This option should be used if the Certificate Signing Request (CSR) was generated elsewhere, or if you used the “Auto-activate” option during the SSL activation. In this case, a Private key (.key or _key.txt) is provided to you during the process.
You will need to create one PFX file from this key and the SSL files to use later in the process.
Steps 1-2 are described above.
If you prefer doing this process using the command line, the next steps will be:
- Upload your certificate file (.crt), and chain file (.ca-bundle) or a PKCS#7 file (.p7b/.cer) on the server. Move or upload the previously created Private key file to the same folder for your convenience.
Note: Technically, it is possible to have the files in different folders too; however, this will make the process more complicated.
- Create the PKCS#12 (PFX) file with this similar OpenSSL command:
openssl pkcs12 -export -out /*Some path*/example.pfx -inkey /*Some path*/example.key -in /*Some path*/example.crt -certfile /*Some path*/example.ca-bundle -name “unifi”
Or openssl pkcs12 -export -out /*Some path*/example.pfx -inkey /*Some path*/example.key -in /*Some path*/example.p7b -name “unifi”
- Add the created PFX file into the keystore:
keytool -importkeystore -srckeystore /*Some path*/example.pfx -srcstoretype PKCS12 -destkeystore *UniFi root*/data/keystore -deststoretype jks -deststorepass *password*
Use your actual UniFi *password*.
- Restart the UniFi controller to apply the changes:
service unifi restart
If you prefer generating the PFX elsewhere (for example, with this online tool), your next steps will be:
- Generate the PKCS#12 (PFX) file using a suitable separate tool.
- Upload the PFX file on the same server where UniFi controller is installed.
- Import the created PFX file into the keystore:
keytool -importkeystore -srckeystore /*Some path*/example.pfx -srcstoretype pkcs12 -srcalias 1 -destkeystore /*UniFi root*/data/keystore -deststoretype jks -destalias unifi -deststorepass *password*
Note: For the PFX file generated elsewhere 1 is used as the default alias. Please specify the -srcalias and -destalias to avoid the error, “Alias unifi does not exist”. Use your actual UniFi *password*.
Sometimes the default alias is different. In such a case you can check the alias with any of the following commands:
openssl pkcs12 -in example.pfx -info
keytool -list -storetype pkcs12 -keystore *example.pfx -v
- Restart the UniFi controller to apply the changes:
service unifi restart
Note: The same process can be done on Windows. For details on how to create the PFX file check the recommended installation method for Windows.
The import itself can be done with a similar command:
“*Java root*\bin\keytool.exe” -importkeystore -srckeystore “*Some path*\example.pfx” -srcstoretype pkcs12 -srcalias 1 -destkeystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore” -deststoretype jks -destalias unifi -deststorepass *password*
*Java root* is specified during the Java installation on your server. By default, it looks like “C:\Program Files\Java\*Java version*\”.
Additional SSL features and tips
Points to consider when setting up an SSL on UniFi:
- It is not possible to use the ECC certificates on UniFi. The system will allow you to import this kind of file, but the SSL will not work.
- Server Name Indication (SNI) is also not supported. So, only one keystore with a certificate can be present on the server at the same time.
Additional SSL-related features allowed on UniFi:
- All versions of UniFi version from 4.x onward automatically enables HTTPS redirect once an SSL is set up. If you enter the default UniFi admin link (by default, https://*UniFi domain name*:8080 in system.properties) then, if the SSL is already installed, you’ll be forwarded to the https:// link (by default, https://*UniFi domain name*:8443).This option works on all UniFi versions starting from 4.x.
- HSTS can be also enabled on UniFi in the system.properties by uncommenting and modifying these lines:unifi.https.hsts=false – use true to enable HSTS.unifi.https.hsts.max_age=*value* – this specifies how long HSTS is cached for (in seconds).unifi.https.hsts.preload=false – set this to true to add your “UniFi domain name” to the preload list. The HSTs will work until you request its removal from the list.unifi.https.hsts.subdomain=false – set this to true if you would like to also apply HSTS policy for subdomains of your domain name, and not only for the main domain name. Generally, this option is not required as UniFi admin normally uses only one hostname.
- You can limit cipher suites and SSL/TLS versions used on UniFi in the system.properties by uncommenting and modifying these lines:unifi.https.ciphers=c1, c2, etc. – replace the values c1, c2, etc. with the actual names of the ciphers you want to;useunifi.https.sslEnabledProtocols=p1, p2, etc. – replace the values p1, p2, etc. with the actual names of the protocols you want to use.Note: The recommended and light (supports outdated browsers) configurations for UniFi can be checked here.