Installing a custom SSL certificate - SonarSoftware/customer_portal GitHub Wiki

The customer portal is only available over SSL (HTTPS) and ships with a self-signed SSL certificate. This will work for testing, but will cause warning messages in customer browsers and should be replaced with a real certificate.

Using Let's Encrypt

If you'd like to use Let's Encrypt for a free SSL certificate, please follow the instructions below.

First, make sure that you have the appropriate DNS entries in place before you begin the process (CNAME, A, AAAA, whatever is right for your implementation.) These records must exist prior to using Let's Encrypt, or the certificate generation will fail.

Run the following commands to install the necessary tools:

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-apache 

You need to enter your hostname into the Apache configuration file for renewal to work correctly. Open the configuration file by typing nano -w /etc/apache2/sites-enabled/000-default.conf. You will see a section that begins with <VirtualHost _default_:443>. On the next line, enter ServerAlias portal.example.com where portal.example.com is your customer portal hostname. Press CTRL+X to exit, and enter Y to save your changes. Now type service apache2 reload to reload it.

Begin the generation of the SSL certificates for your server:

sudo certbot --authenticator webroot --installer apache

You'll be prompted to define which hostname you want to generate a certificate for - the one you entered in the Apache should be the first option. You'll then be asked for the webroot, which is /usr/share/portal/public. This should validate, and generate a new certificate for you.

At this point, your site should be secured with an SSL certificate that's valid for 3 months. The Certbot application will automatically renew it before it expires.

Using a commercial SSL certificate

If you already have an SSL certificate you wish to use, skip to the next step.

To generate a new SSL certificate, you must purchase one from a Certificate Authority - I like Namecheap. There is a great tutorial available on generating the necessary key and CSR to get your certificate from Namecheap. Don't follow the parts regarding installation - we'll do that next.

Installing your SSL certificate

The web server used by the customer portal is Apache - your CA may ask which web server you are using when you download your certificate. If so, choose Apache!

The default, self-signed certificate is in /etc/apache2/ssl. Copy your new certificate files into /etc/apache2/ssl. You should have, at a minimum, a .key file and a .crt file. You will also almost certainly have some kind of intermediate certificate (normally with a name containing Bundle or something similar.)

Once all the files are copied into the /etc/apache2/ssl directory, we need to reconfigure Apache to use these files. Type nano /etc/apache2/sites-enabled/000-default.conf. You will see two or three lines that need to be changed.

To update the key file, find the line that starts with SSLCertificateKeyFile and replace the part that says customerportal.key with the name of your key file.

To update the certificate, find the line that starts with SSLCertificateFile and replace the part that says customerportal.crt with your certificate name.

If you have an intermediate/bundle file, remove the # from the beginning of the line that starts #SSLCertificateChainFile and replace the part that says sonar.ca-bundle with your intermediate/bundle cert filename.

Once you have made these changes, press CTRL+X to exit, type y to save and press enter. We now need to restart Apache - type sudo service apache2 restart.

OK, you're almost done! Finish up by setting a custom logo, securing your portal, and setting up automatic updates.