Before installing an SSL on Heroku, first make sure you have all the essential files:
- Main certificate file with .crt extension (you can download this file from the email received from the Certificate Authority when your certificate is issued)
- CA bundle file (you can download this together with the certificate)
- Private key file which was generated together with CSR on the very first step (see instructions on how to generate CSR)
Note: The installation process involves purchase of SSL Endpoint for your application at Heroku (Heroku SSL Endpoint is a paid service and costs $20/month), import of the certificate files, and DNS configuration.
!Please keep in mind that it is possible to have the certificate installed for *free* using the Heroku SSL option. For this to be done, please use the following command: heroku certs:add example.crt example.key
Once done, please update your DNS settings for each domain on your app accordingly.
* You also need to use the flag --type sni if your app already has the SSL Endpoint add-on enabled to migrate to the free option.
Note: If your certificate was reissued or renewed, you can update it on Heroku with the help of the following command: heroku certs:update server.crt server.key
Please make sure to use the new certificate and the new Key.
1. Create SSL Endpoint by running the following command in the terminal of your local environment:
$ heroku addons:create ssl:endpoint
2. Upload the .crt file into the same SSL directory for your application and combine the main certificate and CA bundle into one separate file using the command:
$ cat example.crt bundle.crt > server.crt
3. Import the certificate and private key to the endpoint with the following command:
$ heroku certs:add server.crt server.key
You will see the details of the certificate and the hostname assigned to your SSL endpoint in the output:
Adding SSL Endpoint to example... done
example now served by example-2121.herokussl.com.
Certificate details:
Expires at:
Issuer:
Starts at:
Note: It may take up to 30 minutes (or as long as 2 hours, in rare cases) for the endpoint to be created.
4. When your SSL endpoint is created, it is necessary to direct requests for your secured domain to the endpoint hostname. If you have not added the domain to your app yet, do it now with the following command:
$ heroku domains:add www.example.com
Adding www.example.com to example... done
To direct requests to the endpoint hostname create a CNAME record:
Record type Name Target
CNAME www example-2121.herokussl.com
Similar record for WildCard certificates:
Record type Name Target
CNAME * example-2121.herokussl.com
IMPORTANT: Setting a CNAME record for the root domain (@) will overwrite all the other records set up for the domain. For this reason, you'll need your certificate to cover the subdomain (www.example.com, sub.example.com, *.example.com) so that you are able to create a CNAME for the subdomain.
It is possible to use a certificate issued for the bare domain (example.com) ONLY if you use a DNS provider that supplies CNAME-like functionality at the zone apex.
All single domain certificates provided by ZTABOX cover both www.example.com and example.com no matter which of the two you use as the Common Name for your certificate.
That's it! Your certificate is now configured and you can access the subdomain over https. To check if the certificate was installed correctly, use any of these checkers:
Note: The SSL Endpoint add-on described in this article is only recommended for supporting legacy Heroku applications, or for applications that require custom security policies. Here's the guide for SSL installation using Heroku SSL option.