How to Install an SSL Certificate on Unifi Cloud Key

This tutorial gives you step-by-step instructions on how to install an SSL certificate on a UniFi Cloud Key. The Cloud Key runs the UniFi Network application on top of a Java keystore, so the install is done over SSH: you build a PKCS#12 bundle from your certificate, private key, and CA chain, then import it into the Cloud Key keystore with the Java keytool utility and restart the UniFi service.

Generate a CSR code on UniFi Cloud Key

The Certificate Signing Request, or CSR, is a block of encoded text that holds your contact details, such as your domain and organization. Every applicant must generate a CSR and send it to the Certificate Authority (CA) for validation before a certificate can be issued. For a Cloud Key, the common name in the CSR should be the hostname you use to reach the controller, for example unifi.yoursite.com.

You have two options:

• Use our CSR Generator to create the CSR automatically.
• Follow our step-by-step tutorial on how to generate a CSR on UniFi Cloud Key.

You can open your CSR file with any text editor, such as Notepad, and paste it during the certificate order process with your SSL vendor. Keep the matching private key safe: you will need it again in Step 3 to build the PKCS#12 bundle. Once the CA validates your request and emails the SSL files, continue with the installation below.

Install an SSL certificate on UniFi Cloud Key

The Cloud Key serves HTTPS from a Java keystore at /usr/lib/unifi/data/keystore. By default that keystore holds a self-signed certificate under the alias unifi, protected by the password aircontrolenterprise. To install your own certificate you replace that entry: bundle your files into a PKCS#12 archive, import it into the same alias, then restart the UniFi service. You will work over SSH, so connect to the Cloud Key first (the default SSH user is root on Gen1, or the admin account you set during adoption on Gen2).

Step 1: Prepare your SSL files

Check your inbox and download the ZIP archive containing your certificate. Extract it. Depending on your SSL provider, you should have some or all of these files:

• The primary SSL certificate (your server certificate).
• The intermediate SSL certificate.
• The root SSL certificate.
• The CA bundle, a single file that already contains the root and intermediate certificates.

You also need the private key you generated together with the CSR. If you used our CSR Generator, the key was offered for download at that time.

Step 2: Copy your SSL files to the Cloud Key

Upload your files to the Cloud Key over SCP or SFTP and place them in /etc/ssl/private/. Use these names so they match the commands in the next steps:

• Primary certificate as /etc/ssl/private/cloudkey.crt
• Private key as /etc/ssl/private/cloudkey.key
• CA bundle (root and intermediate) as /etc/ssl/private/yourcaname.crt

Note: each PEM file must end with a newline after the closing line. The final line of the certificate is exactly five hyphens, the words END CERTIFICATE, then five hyphens (—–END CERTIFICATE—–); make sure there is a line break after it. A missing trailing newline is a frequent cause of import errors.

Step 3: Bundle your certificate into a PKCS#12 file

Combine your private key, primary certificate, and CA bundle into a single PKCS#12 file. The alias must be unifi, because that is the alias the UniFi keystore expects. Replace enteryourpassword with a password of your choice and remember it: you will pass the same value to keytool in Step 4 as the source password.

openssl pkcs12 -export -in /etc/ssl/private/cloudkey.crt -inkey /etc/ssl/private/cloudkey.key -out /etc/ssl/private/cloudkey.p12 -name unifi -CAfile /etc/ssl/private/yourcaname.crt -caname root -password pass:enteryourpassword

This writes /etc/ssl/private/cloudkey.p12, containing the key, your certificate, and the chain, all under the alias unifi.

Step 4: Import the PKCS#12 file into the Cloud Key keystore

Import the PKCS#12 file into the existing keystore at /usr/lib/unifi/data/keystore. The destination keystore already uses the password aircontrolenterprise, so the destination store and key passwords must stay aircontrolenterprise. The source password is the one you set on the PKCS#12 file in Step 3.

keytool -importkeystore -deststorepass aircontrolenterprise -destkeypass aircontrolenterprise -destkeystore /usr/lib/unifi/data/keystore -srckeystore /etc/ssl/private/cloudkey.p12 -srcstoretype PKCS12 -srcstorepass enteryourpassword -alias unifi

If keytool reports that the alias unifi already exists, it is referring to the default self-signed entry. Confirm the overwrite when prompted, or delete the old entry first with the command below and then re-run the import:

keytool -delete -alias unifi -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise

Important: do not change the keystore password to your own value. The UniFi service is hard-coded to open the keystore with aircontrolenterprise; if you change it, the controller cannot read the certificate and HTTPS will fail.

Step 5: Set permissions and remove the temporary files

Tighten ownership and permissions on the files in /etc/ssl/private/ so the private key is not world-readable, then delete the intermediate files you no longer need. Run these commands one at a time:

chown root:ssl-cert /etc/ssl/private/*
chmod 640 /etc/ssl/private/*
rm /etc/ssl/private/cloudkey.p12

The certificate now lives inside the keystore, so the PKCS#12 file is no longer needed. If you also uploaded the CSR or the CA file only for this process, you can remove those too:

rm /etc/ssl/private/cloudkey.csr
rm /etc/ssl/private/yourcaname.crt

Tip: before restarting, you can back up the keystore so you can roll back if needed. From inside /usr/lib/unifi/data/, archive it with tar -cvf keystore-backup.tar keystore.

Step 6: Match the controller hostname to your certificate

So browsers trust the certificate without a name mismatch warning, set the controller hostname or IP to the name in your certificate. In the UniFi Network application, go to Settings > System (older versions: Settings > Controller) and set the Controller Hostname/IP to the common name on your certificate, for example unifi.yoursite.com. Make sure that hostname resolves to the Cloud Key in your DNS.

Step 7: Restart the UniFi service

The new certificate is read only when the UniFi service starts, so restart it to load your certificate:

service unifi restart

On newer Cloud Key firmware that uses systemd, the equivalent command is:

systemctl restart unifi

Wait a minute for the service to come back up, then reload the controller in your browser. Congratulations, your SSL certificate is now installed on your UniFi Cloud Key.

Test your SSL installation

After installing the certificate, check your configuration for errors or vulnerabilities such as a missing intermediate certificate or an untrusted chain. Use our SSL Checker for an instant scan and report. Because the UniFi controller usually listens on port 8443, point the checker at your full address, for example unifi.yoursite.com:8443. You can also confirm the result from the command line:

echo | openssl s_client -connect unifi.yoursite.com:8443 -servername unifi.yoursite.com 2>/dev/null | openssl x509 -noout -issuer -dates

This prints the certificate’s issuer and validity dates, so you can confirm the Cloud Key is serving your certificate and not the old self-signed one.

Frequently Asked Questions