Understanding SSL on Heroku
Last updated 19 July 2019
Table of Contents
There are three ways to enable SSL for your Heroku app’s custom domains (listed in order of recommended use):
- Automated Certificate Management (ACM)
- Heroku SSL
- SSL Endpoint (paid add-on)
In general, your app should use Automated Certificate Management unless it requires functionality that ACM does not support. Summaries for the functionality provided by each method are provided below.
For enabling SSL on apps in Private Spaces, please refer to the documentation here.
SSL is always enabled for .herokuapp.com
for Common Runtime apps.
When to use Automated Certificate Management (ACM)
With Automated Certificate Management (ACM), Heroku automatically manages TLS certificates for apps running on paid dynos on the Common Runtime. Certificates handled by ACM automatically renew one month before they expire, and new certificates are created automatically whenever you add or remove a custom domain.
ACM is recommended for most Heroku apps, because:
- It provides TLS certificates at no additional cost
- It supports creating certificates for multiple domains
- It automatically renews TLS certificates before they expire
ACM does not provide support for:
- Wildcard domains
- EV certificates
If your app requires any of the functionality that ACM doesn’t support, it should use Heroku SSL instead.
DNS Targets for ACM
DNS targets for ACM will end with herokudns.com
for Common Runtime apps, or herokuspace.com
for Private Spaces apps e.g.
example.com example.com.herokudns.com
www.example.com www.example.com.herokudns.com
or
example.com randon-word-odhsycy1xdsqfbqy8gceaa2d.herokudns.com
or for Private Spaces
example.com random-haiku-5196.also-random-3847.herokuspace.com
Again, wildcard domains are not supported by ACM.
When to use Heroku SSL
Heroku SSL is a free service for apps running on paid dynos that allows you to upload your own TLS certificate. You are responsible for purchasing and renewing this certificate.
Use Heroku SSL instead of Automated Certificate Management (ACM) if:
- You want to use an EV certificate
- Your app needs to support wildcard domains
- You are in the process of migrating from using the SSL Endpoint to using ACM
Heroku SSL uses Server Name Indication (SNI), an extension of the TLS protocol. If your app needs to support older browsers that do not support SNI, use the SSL Endpoint add-on instead.
DNS Targets for Heroku SSL
DNS targets for Heroku SSL follow these patterns:
example.com example.com.herokudns.com
www.example.com www.example.com.herokudns.com
*.example.com wildcard.example.com.herokudns.com
When to use the SSL Endpoint
The SSL Endpoint is an add-on that costs $20 per month. With this option, you are responsible for purchasing and renewing your own certificate.
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)
If none of the above considerations applies to your app, either ACM or Heroku SSL is recommended instead.
When uploading your certificate for the SSL Endpoint, you need to include the --type endpoint
option when running the heroku certs:add
command.
DNS Targets for the SSL Endpoint
Applications in the Common Runtime (not Private Spaces) using the SSL Endpoint use the following DNS target pattern:
<random-string>.ssl.herokudns.com