photo credits

Are you still using the Heroku SSL Endpoint instead of the Free SSL? Are you having trouble setting up the certificates and DNS? Here’s a heads up for you.

SSL in Heroku

It’s been a long time since Heroku introduced its Free SSL support and the Automated Certificate Management (ACM) service to deploy SSL certificates issued by Let’s Encrypt automatically and for free, but there are still cases where the old, paid SSL Endpoint must be retained.

Free SSL relies on SNI support, which according to Heroku itself is available on more than 99.9% of the clients out there, and supports TLS 1.0, 1.1 and 1.2. It is hard to imagine a scenario where SNI is not available, but you might want or need to disable older TLS versions, and that's right where the SSL Endpoint comes in (1).

Tips for the SSL Endpoint

Provisioning the add-on

Run: $ heroku addons:create ssl:endpoint -a my-app

my-app represents the Heroku app name, we will also use my-domain.tld as a template domain name in the following instructions.

Uploading the certificates

Please note that since the Free SSL was introduced, some of the heroku certs:* commands must be invoked with the --type endpoint flag to tell the Heroku API that you want to operate on the SSL Endpoint, rather than the Free SSL.

If you have the certificates + intermediate bundle in one file, run: $ heroku certs:add server.crt server.key --type endpoint -a my-app

If the intermediate certificates are shipped in a separate file, run: $ heroku certs:add intermediate.crt server.crt server.key --type endpoint -a my-app

Configuring the DNS

I noticed that the $ heroku certs:add ... command returns a confusing output:

=== Your certificate has been added successfully. Update your application's DNS settings as follows 
Domain               Record Type  DNS Target 
--------------------------------------------------------------------
my-app.my-domain.tld CNAME my-app.my-domain.tld.herokudns.com

If you set your DNS to point my-app.my-domain.tld to CNAME my-app.my-domain.tld.herokudns.com it will not work. According to the latest Heroku documentation at the time of writing, DNS targets for the SSL Endpoints use the *.herokussl.com pattern in the US region and *.herokuapp.com in the EU region. This means that the correct CNAME value to set in your DNS will look like: random-name.herokussl.com or my-app.herokuapp.com.

To discover the correct CNAME value for your apps, run: $ heroku domains -a my-app

You should get this type of output:

Name  Endpoint  Common Name(s)  Expires  Trusted Type 
-----------------------------------------------------
random-00000 random-00000.herokussl.com *.my-domain.tld, my-domain.tld 2099-09-20 00:00 UTC True Endpoint

The Endpoint column shows the correct CNAME value to point your DNS records to.

Notes

(1) At the time of writing, the latest official documentation available on the Heroku website, dated 2018–10–12 and discussing the differencies between SSL solution, states:

You should use the SSL endpoint only if:
- Your app needs to disable TLS 1.0 or 1.1
- Your app needs to support older browsers that do not support SNI (Server Name Indication)

The current version of the SSL Endpoint documentation, dated 2018–04–17, does not actually state how to do it, though.

Originally published at https://www.rockedscience.net on December 10, 2018.