How to download a UniFi SSL certificate on Ubuntu

Setting up SSL certificates on your UniFi Controller in Ubuntu can feel like deciphering ancient hieroglyphs, but don’t worry! This guide will break it down step by step.

Let's dive In!

---

🚨 Before we dive in, please don't host your UniFi Controller using Ubuntu if you work with client networks. Sooner or later this setup will cause issues! It's perfectly fine for home users, but definitely not recommended for businesses. You can try UniHosted for free.

---

Table of Contents

• Why bother with SSL?
• Prepping your Ubuntu server
  • Step 1: Update and upgrade
  • Step 2: Install the required packages
• Getting the SSL certificate
  • Step 3: Generate a CSR (Certificate Signing Request)
  • Step 4: Submit the CSR to a CA
  • Step 5: Download your SSL certificate
• Installing the SSL certificate on UniFi
  • Step 6: Convert your SSL certificate (if necessary)
  • Step 7: Backup and prepare UniFi
  • Step 8: Import your SSL certificate
  • Step 9: Restart the UniFi service
• Troubleshooting Tips
  • 1. Check the Common Name
  • 2. File Path Errors
  • 3. Firewall Issues
  • 4. Intermediate Certificates
• Final Thoughts

Why bother with SSL?

Before we jump into the commands and configs, let's chat about why SSL matters. SSL (Secure Socket Layer) encrypts the communication between your UniFi controller and users, making it harder for any eavesdroppers to mess with your data.

It’s like putting your network communication in a vault. And hey, with HTTPS becoming the standard, it’s good to be on the right side of security practices.

Without SSL, your UniFi controller communicates over HTTP, which is like sending all your sensitive information on a postcard—anyone who intercepts it can read everything.

SSL adds that crucial layer of security, ensuring that the data transmitted between your controller and your users is encrypted and protected from prying eyes.

Prepping your Ubuntu server

Alright, let’s get the stage ready.

Step 1: Update and upgrade

You don’t want any gremlins popping up during the process. So, update your server’s packages to keep everything running smoothly.

sudo apt update && sudo apt upgrade -y

Why do this? Because outdated packages can cause compatibility issues or leave your system vulnerable to security threats. By keeping your server up to date, you ensure that everything works smoothly and securely.

Step 2: Install the required packages

You’ll need a few packages to help handle the SSL certificate. Install them using the command below:

sudo apt install ca-certificates curl openssl

These tools will help you generate, download, and manage your SSL certificates. For example, "openssl" is essential for creating your Certificate Signing Request (CSR) and handling the encryption and decryption of your SSL keys.

Getting the SSL certificate

Now that your server is prepped, let’s dive into the main course: getting that SSL certificate.

Step 3: Generate a CSR (Certificate Signing Request)

The CSR is your ticket to getting an SSL certificate. It’s like an application form that you submit to a Certificate Authority (CA).

Run the following command to generate your CSR and a new private key:

openssl req -new -newkey rsa:2048 -nodes -keyout unifi_ssl.key -out unifi_ssl.csr

Let’s break this down:

• "req -new": We’re creating a new request.
• "-newkey rsa:2048": We’re generating a new RSA key of 2048 bits.
• "-nodes": This skips the option to encrypt the key with a passphrase.
• "-keyout unifi_ssl.key": This is the file where your private key will be saved.
• "-out unifi_ssl.csr": This is the file where your CSR will be saved.

Fill out the required information (Country Name, State, etc.), but make sure the Common Name is exactly the domain name where your UniFi Controller will be hosted (e.g., "unifi.yourdomain.com"). The Common Name is crucial because it tells the Certificate Authority what domain your SSL certificate will protect.

Step 4: Submit the CSR to a CA

Now, take the CSR you just generated and submit it to your chosen CA. You can choose from several providers like Let’s Encrypt, DigiCert, or GoDaddy. Each has its own pros and cons—Let’s Encrypt is free and easy to use, while DigiCert and GoDaddy might offer more features and better support.

For simplicity, let's say you’re using Let’s Encrypt (because free is always good).

With Let’s Encrypt, you can use a tool called Certbot to automate the process.

First, install Certbot:

sudo apt install certbot

Then, request the SSL certificate:

sudo certbot certonly --standalone -d unifi.yourdomain.com

Certbot will take care of the rest. You’ll have to confirm your domain ownership by following the prompts, but Certbot makes it pretty easy. It will challenge your domain (usually by creating a temporary file on your server or a DNS record) to prove that you own it.

Step 5: Download your SSL certificate

After the validation process, Certbot will download and store your SSL certificate, usually in "/etc/letsencrypt/live/unifi.yourdomain.com/". This directory will contain:

• "fullchain.pem": Your signed certificate along with the chain of trust.
• "privkey.pem": Your private key.

These files are the stars of the show. You’ll need them to configure your UniFi controller.

Installing the SSL certificate on UniFi

Now that you’ve got your certificate, it’s time to tell your UniFi controller to use it.

Step 6: Convert your SSL certificate (if necessary)

If your CA provided a ".pfx" file, you’ll need to convert it to the ".pem` format. But since we used Let’s Encrypt, we’re already good to go.

If you need to convert for any reason, you can use this command:

openssl pkcs12 -export -out unifi.pfx -inkey privkey.pem -in fullchain.pem

This conversion is sometimes needed if you’re switching CAs or if your setup requires a different file format. The ".pfx" format bundles your private key and certificate into one file, which some systems require.

Step 7: Backup and prepare UniFi

Before you go any further, it’s smart to back up your existing keystore. Trust me, you don’t want to mess this up and have no way back.

sudo cp /usr/lib/unifi/data/keystore /usr/lib/unifi/data/keystore.backup

This command makes a copy of your current keystore, where all your SSL-related files are stored. If anything goes wrong, you can restore your UniFi controller’s SSL configuration by simply copying this backup file back to its original location.

Now that we have our safety net, let’s move on.

Step 8: Import your SSL certificate

Next, you’ll need to use the "keytool" command to import your new SSL certificate into the UniFi keystore.

Navigate to your UniFi directory:

cd /usr/lib/unifi

Use the following command to import the certificate:

sudo keytool -importkeystore -srckeystore /etc/letsencrypt/live/unifi.yourdomain.com/fullchain.pem -srcstoretype PKCS12 -destkeystore /usr/lib/unifi/data/keystore -deststoretype JKS -srcstorepass changeit -deststorepass aircontrolenterprise -alias unifi

Let’s break it down:

• "-srckeystore": The path to your SSL certificate.
• "-srcstoretype": The type of keystore you're importing from (usually "PKCS12").
• "-destkeystore": Where the keystore file will be saved.
• "-deststoretype": The type of keystore you're creating (usually "JKS").
• "-srcstorepass": The password for the source keystore (replace "changeit" if it’s different).
• "-deststorepass": The password for your UniFi keystore ("aircontrolenterprise" is the default).

Step 9: Restart the UniFi service

Almost there! Just restart the UniFi service to apply the changes.

sudo service unifi restart

Give it a moment to reboot. Then, visit your UniFi controller using HTTPS (e.g., "https://unifi.yourdomain.com"). If all went well, you should see that sweet, sweet padlock in your browser’s address bar.

If you don’t see the padlock, don’t panic. There are a few common issues that can cause this, and they’re usually easy to fix. Let’s go through a few troubleshooting steps.

Troubleshooting Tips

1. Check the Common Name

Ensure that the Common Name in your certificate matches your domain. If it doesn’t, your browser will flag it as a potential security risk.

2. File Path Errors

Double-check that the files are in the correct locations and referenced properly in your commands. A typo in a file path can easily break the entire process.

3. Firewall Issues

Make sure port 443 is open on your server for HTTPS traffic. Without this, no amount of SSL wizardry will get your site to load over HTTPS.

4. Intermediate Certificates

Sometimes, your CA might provide an intermediate certificate that links your site’s SSL certificate to a trusted root certificate. If this isn’t properly configured, your browser might not recognize your certificate as valid. Ensure that any intermediate certificates are included in your "fullchain.pem".

Final Thoughts

And that’s it! You’ve just downloaded and installed an SSL certificate on your UniFi Controller running on Ubuntu. It might feel like a rollercoaster, but now your UniFi Controller is secured with HTTPS. So, sit back, relax, and enjoy the secure connection.

Whether you’re managing a small network at home or a larger enterprise setup, SSL is a must-have for ensuring that your communications remain private and secure. Plus, with HTTPS, you’ll avoid those annoying “Not Secure” warnings in your browser, giving your users confidence in the security of your network.

At UniHosted, we understand that managing your network can sometimes feel overwhelming. That’s why we offer hosting for your UniFi Controller in the cloud, taking care of updates, backups, and security (including SSL management).If you would like me to personally walk you through UniHosted, you can schedule a call with me here.