<img src="//bat.bing.com/action/0?ti=5129185&amp;Ver=2" height="0" width="0" style="display: none; visibility: hidden;">

Use Let's Encrypt with HipChat Server



It is best practice to use SSL and HTTPS to secure communications between your users and your website and avoid the potential security risk that unencrypted traffic poses. HipChat Server ships with a "self-signed" certificate, requiring you to arrange and install your own "trusted" certificate. A trusted certificate would usually require you to contact a Certificate Authority and paying an annual fee. By using Let's Encrypt, you can generate a free, trusted SSL certificate to provide encrypted communications between your users and HipChat. Best of all, we can set the certificate to automatically renew before it expires.

HipChat Server

HipChat Server offers a self-signed certificate out of the box. This is great for testing your configuration but not so great once your want to start using HipChat in production within your organisation. You can update the SSL certificate used by your HipChat instance by going to "Server Admin" and clicking "SSL".


Even if you use Let's Encrypt to generate the certificate on your local machine and pasted the details into this window, you would run into two problems here:

  1. Let's Encrypt certificates are only valid for 90 days from when they are issued
  2. You have to go through a manual process of checking if they're up for renewal and updating the SSL details in HipChat.

The .ova virtual machine that HipChat Server ships on doesn't play nicely with the "letsencrypt" package that you would use on a normal server.

Solution

HipChat Server ships as a virtual machine image file (.ova). You'll need to log in to your HipChat Server virtual machine image over SSH.

To get to the root account on your HipChat Server image use:

sudo /bin/dont-blame-hipchat 


We suggest using another tool called 
ZeroSSL that works with Let's Encrypt. Go to the ZeroSSL website and follow the installation instructions to get the package installed on your HipChat Server instance.

Important

To prove that you own the domain in question, you will be required to either add a TXT record to your domain OR place a file on your web server that Let's Encrypt can see.

For Option 2 (place a file on your web server that Let's Encrypt can see), follow the below:

mkdir -p /hipchat/web/current/www/.well-known/acme-challenge/
chmod -R 775 /hipchat/web/current/www/.well-known/

Once you've got the ZeroSSL tool installed and you've decided to either add a TXT Record to your domain or create a folder as described above, you are all set to go.

Make a folder for your new certs:

mkdir -p /hipchat/certs/letsencryptcerts

Now you are ready to generate your certificate:

le.pl --key account.key --csr domain.csr \
--csr-key domain.key --crt domain.crt --domains "HIPCHAT.MYDOMAIN.COM" \
--path /hipchat/web/current/www/.well-known/acme-challenge/ \
--generate-missing --unlink

If that went OK and it worked, then you can add the "–live" option to implement this for real:

le.pl --key account.key --csr domain.csr \
--csr-key domain.key --crt domain.crt --domains "HIPCHAT.MYDOMAIN.COM" \
--path /hipchat/web/current/www/.well-known/acme-challenge/ \
--generate-missing --unlink --live

Add the New Certificate to HipChat

You can provide your PEM file (private key and certificate in one file) to HipChat through the browser or command line:

Warning: Feeding HipChat Server a new certificate will cause it to restart

hipchat certificates -i server.cert.pem

If all goes well, HipChat will say "Importing Certificate/Key" before restarting.

Automating the Process

Automating a renewal within 90 days of the certificate getting issued avoids the headaches of having to manually manage your certificates. 

First you will need to add a script renew_certs.sh in the same directory you have been using for the certificates:

# Remove the "--live" flag to simulate the renewal
# Renews certs if there is < 10 days remaining
le.pl --key account.key --csr domain.csr \
--csr-key domain.key --crt domain.crt --domains "HIPCHAT.MYDOMAIN.COM" \
--path /hipchat/web/current/www/.well-known/acme-challenge/ \
--generate-missing --unlink --renew 10 --live  \
&& cat domain.crt domain.key > server.crt.pem \
&& hipchat certificates -i server.crt.pem

Next:

sudo crontab -e

Finally:

@weekly /hipchat/certs/letsencryptcerts/renew_certs.sh

This will ask Let's Encrypt on a weekly basis if your certificates need renewing.

And that's it! Your domain should have SSL enabled and be auto-renewing the certificates.