Knowledge Base

Installing a SSL certificate on Heroku SSL

Heroku is moving away from using SSL Endpoints and replacing it with a new feature: Heroku SSL. Heroku SSL is a free feature that allows for the managing of SSL/TLS encryption for custom domains and relies on the Server Name Indication (SNI). Please note that Heroku SSL is currently available under Heroku paid plans only.

SSL Endpoints, however, are still available regarding instances where the applications need legacy clients and browser compatibility. If you wish to migrate from SSL Endpoints to Heroku SSL, feel free to use this Heroku guide.


Prerequisites

Once the activation and validation steps are completed, your certificate will be issued and you can proceed with the SSL installation. In order to install the SSL certificate via Heroku SSL, the following files should be used:

  • An issued SSL certificate file for your domain name, e.g. a file with a .crt or .pem extension.
  • The CA Bundle file, which is a chain of certificates that is usually installed in order for browsers to verify that the certificate was issued by a trusted Certificate Authority, usually, it is provided with the certificate itself as the file with .ca-bundle extension. Once the certificate is issued, both certificate and its bundle can be downloaded from ZTABOX email.
  • The corresponding Private Key file with .key extension. Your Private key is generated along with the CSR code that was used to activate the certificate. (This resembles the CSR code and looks like some number of lines with random symbols.) This code starts with '----BEGIN RSA PRIVATE KEY-----' and ends with '-----END RSA PRIVATE KEY-----' tags.

For Heroku, it's necessary to combine the certificate and the CA Bundle into one file. You can open the .crt and .ca-bundle files using any plain text editor, pasting the codes from the .ca-bundle file just below the code in .crt file (make sure that there are no spaces between the codes).

In corresponding command line, you can combine the files using the following command:

cat yourcertificate.crt bundle.ca-bundle > server.crt

You can also create a combined file using this tool: here. Simply paste your certificate code in the box > click on 'Decode' > download the file in the 'Bundle (Nginx)' field.


Installation via Heroku Dashboard

To install the certificate in your Heroku Dashboard, open the certificate, select the necessary application from the list, and select the 'Settings' tab.

Then, scroll down the page and in the 'Domains and certificates' section click on 'Configure SSL'.

In the window that appears on your screen, select 'Manually' from the list and click on 'Continue'. On the first screen, simply drag and drop the combined certificate + bundle file to the box and click on 'Continue'. After that, do the same with the Private Key file.

It's also possible to paste the codes manually (using the 'paste the contents of the file directly' option in the box). You can open the files with any text editor (like Notepad for Windows or TextEdit for Mac), copy the contents and paste them into the boxes.

Once done, Heroku will prompt you to update the DNS records of the custom domain/subdomain. You will need to create a CNAME record using the values displayed to you. The 'Host' value ('Name', etc.) is your domain/subdomain and the 'Target' value ('Points to', etc.) is yourdomain/subdomain.herokudns.com.

Basically, you need to follow this pattern:

yourdomain.com CNAME yourdomain.com.herokudns.com
or
www.yourdomain.com CNAME www.yourdomain.com.herokudns.com

After you made sure that the DNS is configured, click on 'I've done this' and then click on 'Continue'. Please keep in mind that it may take some time for the DNS to be updated globally.

That's it, your domain is now accessible via HTTPS. You can verify the installation by using this tool.


Installation via CLI

Another way to install the certificate is via the command line.

The process is pretty short. Upload the certificate + bundle (combined as described in the 'Prerequisites' section) and Private Key files to Heroku using the heroku certs:add server.crt server.key command.

In case when there is no default Heroku app, you will need to specify it as well using the --app flag, so the command will look like this: heroku certs:add server.crt server.key --app yourappname.

To check if the correct certificate is installed at the moment, you can run the heroku certs:info command.

Please note that you may get an 'Internal server error' when adding your certificate. The reason may be that you are using an outdated version of the Heroku CLI. In this case, you can check your CLI installation and update it to the latest version with the heroku update command or reinstall the CLI itself.


Removing Certificates

If you need to remove the certificate, it can be done via the same menu. Just navigate to 'Domains and certificates' > click on 'Configure SSL' > select 'Remove' > click on 'Continue' > enter the name of your app and click 'Remove SSL'.

To remove the certificate using the command line, simply run the command heroku certs:remove and enter the app name for confirmation.


Updating Certificates

When you need to replace an installed certificate with another one (e.g. the certificates were reissued, you received a completely new certificate or it's time to renew), the installation process will stay the exact same in the Heroku dashboard.

For command line, only one thing will differ: you will need to use the heroku certs:update command instead of heroku certs:add, so it will look like: heroku certs:update server.crt server.key.

Also, we recommend setting up the HTTPS redirect so that the website is accessible only via a secure HTTPS connection.

However, in case of Heroku, this setting will depend on the programming language, framework, and tools you used to build your app. There is no general way to set up the HTTPS redirect that will surely work on all apps.