Automated Certificate Management and compatibility with Android versions prior to 7.1.1

Change effective on 12 November 2020

Summary

Starting January 11, 2021, automatically generated certificates (using Heroku ACM) used for TLS/HTTPS termination on Heroku will become incompatible with most software running on Android versions prior to 7.1.1 (around 34% of currently active Android devices). Software on those devices (like browsers that access Heroku web apps or Android apps interacting with backend APIs on Heroku) will start seeing certificate errors after January 11, 2021 if the Heroku apps or APIs accessed by the software use ACM certificates. ACM certificates apply to:

  1. Custom domains on Common Runtime and Private Space apps with ACM enabled
  2. <appname>.herokuapp.com for all Private Space apps

If your app is affected and you need to maintain compatibility with affected Android devices you have to complete the following steps before January 11, 2021:

  1. Manually get a trusted, signed certificate for relevant custom domains (make sure it’s trusted by pre-7.1.1 Android)
  2. Disable ACM
  3. Upload the manually created certificate to Heroku

If you’re relying on the built-in <appname>.herokuapp.com domain with a Private Space app you will also have to transition to a custom domain, follow the steps above to get a trusted certificate for that custom domain and then transition Android clients from using the <appname>.herokuapp.com domain to the new custom domain.

Background

Heroku Automated Certificate Management (ACM) relies on Let’s Encrypt to issue certificates and Let’s Encrypt is changing how certificates are signed. Unfortunately the change means that certificates issued by Let’s Encrypt (and thus Heroku) will no longer be trusted by most software running on Android versions before 7.1.1.

Heroku site owners that need to maintain compatibility with these Android clients can disable Heroku ACM and use Android-trusted certificates obtained separately from other Certificate Authorities, although that means manually updating certificates as they expire in the future. If you want to keep using ACM, you could instruct end-users to use the Firefox browser on affected Android devices as that browser ships with its own up-to-date certificate bundle.