Skip to main content

Search

How can we help ?

Ubiquiti - Install a custom Certificate

Alexandre de THOMASSON
  • Updated

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:

  1. Connect to your server through the command prompt.

    • On Linux-based servers, you can use Putty (on Linux- or Windows-based machines) or a similar application.

    • On MacOS, run the Terminal application.

    • On the Windows server, run cmd or PowerShell (connected via remote desktop if needed).

  2. 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 or sudo user access. For this, you can run the following command on the Linux-based system:

    sudo su -

  3. Go to the UniFi controller main folder by running:

  4. 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"

  5. 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:

  6. 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.

  7. Restart the UniFi controller to apply the changes:

  8. 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).

  1. Open the current keystore file in Keystore Explorer using the default password aircontrolenterprise or the one used by the controller.

    TIP: You can open the system.properties file and add your custom password in it:

    app.keystore.pass=*password*

    The file is located in the in the data subfolder of UniFi base folder.

  2. 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.

  3. Switch back to Keystore Explorer and delete the unifi entry.

  4. Click: Tools Import Key Pair PKCS12.
    Locate your PFX file and use the password you set during its creation.

  5. The Key Pair Entry Alias should be set as unifi.

  6. Provide the new password. It should be the keystore password (aircontrolenterprise unless it was changed in your UniFi settings).

  7. Save the keystore file using File Save (or simply click on the related icon).

  8. 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 in system.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 starting 4.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 HSTS
    unifi.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 specifically
    unifi.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 enable
    unifi.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.