Certificates for HTTPS

X.509 certificates are used to authorize and secure communications with the server. They are mainly used for HTTPS, but can also be used for SIPS, CTIS, WSS, etc.

This article is about the certificate used for HTTPS.

Wazo and HTTPS

Wazo uses HTTPS mainly for receiving and responding to REST API calls. The REST API calls can occur inside the Wazo Engine, i.e. between Wazo daemons, or outside the Wazo Engine, e.g. for the web interface or any other application based on the REST APIs.

From the outside of the Wazo Engine, every API call is reverse-proxied by nginx, which listens on port 443 (HTTPS) and distribute REST API calls to the right daemon. This means we only have to change one certificate (the one used by nginx) to enable all APIs to be secured by this certificate from the outside of the Wazo Engine.

The default HTTPS certificate used by the Wazo Engine is located in /usr/share/xivo-certs/server.crt with its associated server.key private key.

Let’s Encrypt

To create a new certificate for your Wazo Engine via Let’s Encrypt for the domain wazo-engine.example.com, here is the procedure:

apt install python3-certbot-nginx
certbot --nginx -d wazo-engine.example.com
# answer the questions
systemctl restart nginx

For more details, see the official Certbot documentation.

Use your own certificate

You will need:

  1. the private key used to create your certificate (here named /usr/local/share/private-key.pem)

  2. the full-chain certificate. It must include all intermediate certificates used in the chain of trust (here named /usr/local/share/certificate.fullchain.pem). See the nginx documentation for more details.

  3. Both files must be readable by the group www-data. You can check with the following command:

    sudo -u www-data cat /usr/local/share/*.pem > /dev/null

Edit the file /etc/nginx/sites-available/xivo and replace the following keys:

ssl_certificate /usr/share/xivo-certs/server.crt;
ssl_certificate_key /usr/share/xivo-certs/server.key;


ssl_certificate /usr/local/share/certificate.fullchain.pem;
ssl_certificate_key /usr/local/share/private-key.pem

Then restart nginx:

systemctl restart nginx

Revert previous custom HTTPS certificate configuration

Up to Wazo 18.03, the procedure to install a custom HTTPS certificate was much more complex. This complex procedure is not needed anymore and should be removed to avoid any conflict with future upgrade. You can use the following removal procedure before of after the above configuration steps.

Here is the removal procedure:

# backup your certificate / key (optional)
cp /usr/share/xivo-certs/server.{key,crt} /var/backups

# stop all Wazo Engine services
wazo-service stop all

# regenerate self-signed certificate
rm /usr/share/xivo-certs/server.{key,crt}
dpkg-reconfigure xivo-certs

# remove custom config files
rm /etc/xivo/custom/custom-certificate.yml
rm /etc/{wazo,xivo}-*/conf.d/010-custom-certificate.yml
rm /etc/xivo/custom-templates/system/etc/hosts

# restart services
wazo-service restart all

Then, the last steps:

  • update your directories of type wazo to use:
    • the domain localhost
    • the certificate located in /usr/share/xivo-certs/server.crt