Automated Certificate Management

Last updated 17 April 2018

With Automated Certificate Management (ACM), Heroku automatically manages TLS certificates for all apps that have Hobby and Professional 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. All applications with paid dynos include ACM for free.

Automated Certificate Management uses Let’s Encrypt, the free, automated, and open certificate authority for managing your application’s TLS certificates. Let’s Encrypt is run for the public benefit by the Internet Research Security Group (ISRG).

Setup

Enable Automated Certificate Management

If your app is currently running on Free dynos, Automated Certificate Management is enabled automatically when you upgrade your app to use Hobby or Professional dynos:

$ heroku ps:resize web=hobby

If your app is already running on Hobby or Professional dynos, you can enable ACM by running the following command:

$ heroku certs:auto:enable

View your certificate status

It takes approximately 45 - 60 minutes to fully generate a TLS certificate for custom domains on your application. You can view the status of the certificate that is generated for all of your custom domains by running:

$ heroku certs:auto

If your certificate is currently being generated, you may see different states next to the custom domains on your application.

Providing your own TLS certificate

If you’d prefer to use a different type of TLS certificate, such as one from a different CA, a wildcard certificate, or an EV certificate, you can easily do so.

Simply upload your own certificate, following the steps listed in the Heroku SSL Dev Center article.

Providing your own certificate disables ACM for your application. If you want to re-enable ACM, you can run:

$ heroku certs:auto:enable

Turning off Automated Certificate Management

You can easily turn Automated Certificate Management off by running:

$ heroku certs:auto:disable

This removes your domain’s certificate and turns off ACM for your application. Removing your certificate with heroku certs:remove also turns off ACM.

Migrating existing applications

Migrating from Heroku SSL with your own certificate

Automated Certificate Management uses the same DNS configuration as our existing Heroku SSL (SNI) support. Although it might take some time to verify your DNS configuration, your app will continue to serve your existing SSL certificate while verification is taking place. Your app should continue to remain available at your custom domain throughout the process.

Migrating from SSL Endpoint

Migrating from the SSL Endpoint addon to Automated Certificate Management requires a DNS change. However, you can use Heroku SSL (SNI) as an intermediate step to avoid downtime for your custom domain. Start by following these instructions to migrate from SSL Endpoint to Heroku SSL (SNI). Once that process is complete, you can enable ACM with no downtime as described above.

Troubleshooting

Verification errors

If heroku certs:auto shows “Failing” or “Failed” for any domain when you run heroku certs:auto, it means Heroku was unable to verify DNS for a given domain. You need to verify that it is pointed to the correct DNS target as specified in heroku domains. The DNS targets will be in the format <your-domain>.herokudns.com.

If your DNS is pointed at older DNS settings, such as *.herokuapp.com or *.herokussl.com, Heroku will not be able to generate a certificate.

If ACM is unable to create a certificate for your domain, you receive a notification after three days of attempts. In most cases, this error occurs because DNS is not properly configured for your domain. After you resolve your DNS issue, run the following command to instruct ACM to try again:

$ heroku certs:auto:refresh

Failure reasons

There are a number reasons why issuing a certificate might fail. A failure reason may be included in a notification email or in the CLI.

Incorrect DNS settings

Your DNS record is not set up properly.

Review this document and ensure that your DNS records are set up correctly.

DNS provider doesn’t support CAA

Let’s Encrypt returned an error that your DNS provider does not support Certificate Authority Authorization (CAA) records.

Contact your DNS provider for more information on CAA support. Learn more about CAA records.

CAA record prevents issuance

The CAA record prevents certificates from being issued by Let’s Encrypt.

Add a CAA record that allows Let’s Encrypt to issue certificates for the domain. Learn more about CAA records.

Domain record does not exist

Let’s Encrypt has returned a NXDOMAIN error, which means the domain record does not exist in your DNS provider.

To fix this error, please make sure that your domain name was entered correctly and the DNS record for the domain contains the right CNAME.

Domain considered unsafe

Let’s Encrypt checks domains against Google’s Safe Browsing API and will not issue certificates for domains considered unsafe.

Check the status of your domain by visiting this URL: http://www.google.com/safebrowsing/diagnostic?site=http://yourdomainhere.com/

Let’s Encrypt domain blacklist

You have requested a certificate for a domain on Let’s Encrypt’s domain blacklist. Typically, well-known domains are on this blacklist as an additional security measure to prevent unauthorized certificate creation.

Contact Let’s Encrypt on their Community Support forum.

Known limitations

• ACM does not support applications that have over 100 custom domains.
• ACM does not support applications that have wildcard custom domains.
• ACM does not support the SSL Endpoint add-on.
• ACM is currently available for apps on the Common Runtime only. It is not yet available in Private Spaces.
• ACM is not available if your app is behind a CDN such as Cloudflare or Fastly.

Alternatives

• If you want to automatically renew a wildcard certificate, or use a different CA, we recommend checking out providers in our ecosystem such as SSL FastTrack or ExpeditedSSL.