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).
Mar 16, 2018 Convert certificate and key. UniFi Controller uses the Java keytool to manage its keys, so it doesn’t understand.pem files. I had to convert it. This created a file called ubnt.p12 that I use in the next step. Openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem -out ubnt.p12 -name ubnt -password pass:aTempPassword Install certificate. Mar 31, 2020 Ubiquiti UniFi: First Impression. (SSH) access. VLAN support. Additionally, the UniFi Dream Machine has a UniFi Cloud Key and matching controller software built-in. Related: AmpliFi Alien Router Review. The only downside to the UniFi Dream Machine is the lack of Wi-Fi 6 support.
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:
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:
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:
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:
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 ‘nr’ < * 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++:
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:
SSL Installation options for UniFi on Linux/MacOSSSL 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):
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*binkeytool.exe” -import -trustcacerts -alias unifi -file “*some3 path*example.p7b” -keystore “C:Users*account username*Ubiquiti UniFidatakeystore”
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:
Note: Technically, it is possible to have the files in different folders too; however, this will make the process more complicated.
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”
keytool -importkeystore -srckeystore /*Some path*/example.pfx -srcstoretype PKCS12 -destkeystore *UniFi root*/data/keystore -deststoretype jks -deststorepass *password*
Ubiquiti Unifi Manual
Use your actual UniFi *password*.
service unifi restart
If you prefer generating the PFX elsewhere (for example, with this online tool), your next steps will be:
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
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*binkeytool.exe” -importkeystore -srckeystore “*Some path*example.pfx” -srcstoretype pkcs12 -srcalias 1 -destkeystore “C:Users*account username*Ubiquiti UniFidatakeystore” -deststoretype jks -destalias unifi -deststorepass *password*
*Java root* is specified during the Java installation on your server. By default, it looks like “C:Program FilesJava*Java version*”. Additional SSL features and tips
Points to consider when setting up an SSL on UniFi:
Additional SSL-related features allowed on UniFi:
To get an SSL certificate, a Certificate Signing Request (CSR) code is required.
On UniFi controller software, a CSR code is generated along with the default UniFi keystore. Follow these steps to generate the keystore:
Step 1: First, connect to the server where the controller is installed with the help of the appropriate command prompt.
Note: Run all further commands with administrator rights (on Windows) or under the root or sudo user (on Linux/MacOS):
Step 2: Generate the CSR code, using the following command:
java -jar *UniFi root*/lib/ace.jar new_cert example.com “Company” “Location (city)” “State or province” “Country code”
(for Linux/Mac OS) Generate Ssh Key Github
or
java -jar “*UniFi root*libace.jar” new_cert example.com “Company” “Location (city)” “State or province” “Country code”
(for Windows)
Important:If any of the CSR values have more than one word, put them in quotation marks (“). Otherwise, the second word will be moved to the value of the next field, which may invalidate the CSR. However, it should be noted that the server will not show an error message if this happens.
Note: The *UniFi root* depends on the system you have UniFi controller installed on:
Useful tip: Alternatively, open the UniFi root folder first, using the command cd *Unifi root*, and then run the CSR generation command in it. This way you won’t need to specify the full path in the command itself.
You will then receive two files: unifi_certificate.csr.pem and unifi_certificate.csr.der in the /*Unifi root*/data folder. The second file has different formatting and is not used normally.
The text code from the unifi_certificate.csr.pem file can be used for the SSL activation.
Important: Instead of a Private key, UniFi creates a keystore file named keystore in /*UniFi root*/data/ (or simply *UniFi root* on some systems), to which you will only need to upload the certificate files after the issuance.
Step 3: To open the file and extract the text code, do one of the following:
Footnotes:
If you use the option “Auto-activate” during the SSL activation, this whole process can be skipped. However, it will require a specific installation process.
Ubiquiti Ssh Info
As a general rule, for UniFi on Windows the “Auto-activate” option may be more convenient, while in other cases it is easier to use the CSR created on UniFi.
Comments are closed.
|
AuthorWrite something about yourself. No need to be fancy, just an overview. Archives
December 2020
Categories |