Heroku is transitioning away from SSL Endpoints and introducing a new feature: Heroku SSL. Heroku SSL is a free feature that enables the management of SSL/TLS encryption for custom domains, utilizing the Server Name Indication (SNI). Please be aware that Heroku SSL is currently exclusively available under Heroku’s paid plans.
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 your 1Byte account.
- 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.
| Please keep in mind that 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: https://ssl-checker.1byte.com/. 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 Settings.
Then, scroll down the page and click on Configure SSL in Domains and certificates section.
In the window that appears on your screen, select Manually from the list and click Continue. On the first screen, simply drag and drop the combined certificate + bundle file to the box and click 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 SSL checker 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 Prerequisites section of this guide) 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’ message 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 Configure SSL >> select Remove >> click 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.