Understanding TLS on Heroku
Last updated September 30, 2024
Table of Contents
There are two ways to enable TLS for your Heroku app’s custom domains. The options are listed in order of recommended use:
- Automated Certificate Management (ACM)
- Heroku SSL
In general, use Automated Certificate Management unless your app requires functionality that ACM doesn’t support. This article provides summaries of the functionality provided by each method.
For enabling TLS on apps in Private Spaces, refer to the documentation here.
TLS 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 the Common Runtime. Certificates handled by ACM automatically renew one month before they expire, and new certificates are created automatically whenever you add 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 doesn’t support:
- Private Space apps using wildcard domains
- OV/EV certificates
- Apps using internal routing
If your app requires any of the functionality that ACM doesn’t support, use Heroku SSL instead.
DNS Targets for ACM
DNS targets for ACM end with herokudns.com for Common Runtime apps, or herokuspace.com for Private Spaces apps. For example:
example.com example.com.herokudns.com
www.example.com www.example.com.herokudns.com
Or
example.com random-word-odhsycy1xdsqfbqy8gceaa2d.herokudns.com
*.example.com random-word-odhsycy1xdsqfbqy8gceaa2d.herokudns.com
Or for Private Spaces
example.com random-haiku-5196.also-random-3847.herokuspace.com
Note that ACM doesn’t support wildcard domains for Private Spaces
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’re responsible for purchasing and renewing this certificate.
Use Heroku SSL instead of Automated Certificate Management (ACM) if:
- you want to use an OV/EV certificate
- your app must support wildcard domains on Private Space apps
- your app uses internal routing
Heroku SSL uses Server Name Indication (SNI), an extension of the TLS protocol.
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