Ubiquiti Unifi Controller SSL Certificate creation process

Published by Jeroen Tielen on

Ubiquiti has a little article on the site how to add yout own ssl certificate to your Unifi controller. But they made it a bit to complex ๐Ÿ˜‰ Read article.

First let me explain what kind of certificate the Unifi controller wants to have:

  1. The controller works with a keystore file. In this file the whole certificate chain and key file must be included;
  2. The keystore file must have password: aircontrolenterprise (can be changed);
  3. The keystore file must have alias: unifi.

The keystore file is located in: /usr/lib/unifi/data (Linux) or %UserProfile%/Ubiquiti Unifi (Windows).

Open the current keystore file in “Keystore Explorer“. If you can’t open it with password: aircontrolenterprise then you need to make sure the controller is using this password. Follow these steps to do this:

  1. Rename current keystore file so the controller can’t use it anymore (or just delete it);
  2. Edit /usr/lib/unifi/data/system.properties and add line: app.keystore.pass=aircontrolenterprise
    Note: You could also choose your own password here;
  3. Restart the controller and there will be a new keystore file generated;
  4. try to open this file in keystore explorer with the correct password.

If you can open the file with the given password we need to replace the current self-signed certificate with your own certificate.

First create 1 cer file which holds the certificate and intermediate certificate(s). Open a new text file in notepad, or your favorite text editor. Paste the certificate followed by the intermediate certificate(s). The file should look like this:

If you have more than 1 intermedate certificate just add them all. Start with your own SSL certificate and follow the chain up to the Root CA.

Note: You don’t have to provide the Root CA certificate as this should already be present on the endpoints connecting to your Unifi controller.

Now we need to create a PFX (PKCS12) file which holds the just created cer file and the key file. If you don’t have already please install openssl.

The command to create the PKCS12 file is: openssl pkcs12 -export -in <you_cer_file_with_the_chain>.cer -inkey <you_key_file>.key -out <name_it>.pfx

Choose you own password for this. This could be different than the password used in the Unifi controller.

Now switch back to keystore explore and delete the unifi entry.

Click: Tools –> Import Key Pair –> PKCS12. Locate the PFX file and give the password you gave during creation of the pfx file.

The Key Pair Alias should be: unifi

And provide the new password. This should be the password you have set in the Unifi controller (aircontrolenterprise).

Save the keystore file and copy it to the Unifi controller. Restart controller and you are good to go ๐Ÿ™‚


Jeroen Tielen

Experienced Consultant/Architect with a demonstrated history of working in the information technology and services industry. Skilled in Citrix, Microsoft, VMware, Ivanti, etc.

25 Comments

Mike · February 2, 2019 at 01:35

Where do I get the .key file?? it like you missed a step.

    Jeroen Tielen · February 2, 2019 at 04:18

    The .key file is part of your own certificate. It holds the private key of your certificate. This article does not descibe the process of creating a certificate signing request etc etc.

      Mike · February 2, 2019 at 05:07

      Thanks for the Quick Reply. Your article got me 75% there. Where i got stuck was using openssl to generate the PFX file. After quite a few failed attempts and after banging my head on the wall for about 2 hrs, I ended up replacing your openssl steps with installing a cert on the server and then used windows to export and create the PFX. I then used Keystore explorer to import the PFX windows made into the keystore following the steps you outlined.

        Jeroen Tielen · February 2, 2019 at 07:16

        Haha yeah Ubiquiti should make this easier. But you got it working now?

          Mike · February 4, 2019 at 17:00

          Yep, since this work out to be an all GUI way of doing it, I should do a write up for the windows Controller installs that are out there.

          Jeroen Tielen · February 5, 2019 at 16:58

          This write up is also for the Windows versions. Only file locations are different. But these locations are in this og post ;).

Alessandro · February 5, 2019 at 16:51

I tried my wild card certificate but it doesn’t work what’s wrong?

    Jeroen Tielen · February 5, 2019 at 16:57

    Could be miljons of things. What specific error do you get or what isnโ€™t working?

alessandro · February 5, 2019 at 17:12

Unifi controller says the certificate is invalid

    Jeroen Tielen · February 5, 2019 at 17:13

    Do you have a link to a screenshot?

      alessandro · February 6, 2019 at 14:56

      Yes I have. (Link removed by Jeroen)

        Jeroen Tielen · February 6, 2019 at 15:02

        Hi alessandro,

        It is nog the controller who give that error but your browser. It looks like your domain name doesn’t match your certificate name. Or you dont have the SAN field filled in the certificate. Google Chrome is monitoring on this, and if this is not present it will present an error. More info on this subject: https://support.google.com/chrome/a/answer/7391219?hl=en

Slawek · February 5, 2019 at 20:50

Hi,

Custom SSL works, but Cloudkey every few days replaces my SSL with self-signed one. Why? How to stop it? I have to upload keystore with custom ssl every few days, and then restart unifi service.

    Jeroen Tielen · February 5, 2019 at 20:51

    Hi Slawek, I dont have a cloudkey so I dont know. Iโ€™m running the Unifi controller on a linux virtual machine.

Mark Huggins · March 13, 2019 at 15:31

I feel so close to figuring this issue out but keep hitting a snag. I created the certificates to be signed and got them signed by SSLs/Namechap, I can access the keystore, I got all my certs together in one file, but not exactly sure how to make or get my key file…. Should I extract it from the certificate I got back from SSLs? Only showing public key for that one.

Got them all installed via Java but then get protocol error, so I’m trying this method hoping it will work.

Thanks in advance!

Martin · March 15, 2019 at 17:51

Hi,
I wanted to inquire if you can tell me by following your steps from OP by deleting the keystore then it will recreate a new one. If the new one is recreated, will it have a new self signed time stamp?

I have tried to post in ubnt forum: https://community.ubnt.com/t5/UniFi-Routing-Switching/SSL-Certificate-default-renewal-for-Unifi-Controller-UCK-gen1/m-p/2683881/highlight/true#M134172 but no one seems to be answering nor ubnt support to answer my question. They just said not supported.

I understand that you don’t have UCK cloud key but wanted to see when the key is gone, will it generate a new fresh one and can be used right away. Not worrying about prompt as long the self signed certificate gets renewed.

Thanks in advance!

    Jeroen Tielen · March 15, 2019 at 17:54

    Correct. It will created a new one. You can test it yourself by backing up your current keystore file and remove it from the controller.

      Martin · March 15, 2019 at 18:05

      Thanks. I will try it tonight when I get home. I should have asked here to begin with ๐Ÿ™‚

      Martin · March 16, 2019 at 21:56

      Jeroen,
      It worked :). Simple removal, restart and it will generate a new self signed key for another 10 years.

      I will play around later with a custom one.

      Cheers.

        Jeroen Tielen · March 17, 2019 at 12:49

        Now you have 10 years to create a custom one ๐Ÿ˜‚๐Ÿ˜‚

Vojtech · August 3, 2019 at 12:00

Jeroen, thank you so much for this article, it really cleared things for me.

Cheers
Vojtech

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this:
WordPress Appliance - Powered by TurnKey Linux