How do I manually migrate off my SSL Endpoint Add-On?

Issue

You want to manually migrate your application off of the SSL Endpoint Add-On because of the SSL endpoint deprecation

Resolution

Summary

SSL Endpoints was released in 2012 and has been used by tens of thousands of Heroku apps. Over the years we’ve introduced newer TLS termination options that are automated, more flexible and at a lower price point for customers. For this reason, and because SSL Endpoints relies on previous-generation infrastructure, we have decided to retire the feature.

You probably added SSL Endpoints to your Heroku apps for one or more of these reasons:

  1. Wanted https on a custom domain
  2. Wanted to disable TLS 1.0 or disable TLS 1.0 and 1.1
  3. Wanted to use multiple different certificates with a single Heroku app
  4. Wanted to use a wildcard certificate or other specific certificate (that clients pin to, for example)

Migration Considerations:

TLS 1.2+ Enforcement: Starting August 2, all common runtime apps will transition to TLS 1.2+ only (no TLS 1.0 or TLS 1.1), so the migration away from SSL Endpoint will not weaken TLS settings for your app if you relied on SSL Endpoints to disable TLS 1.0 or TLS 1.1.

SNI Protocol: Note that after the migration, your app will require clients to connect using the widely supported SNI (Server Name Indication) protocol after migrating to the Heroku SSL feature. SNI is supported with Android version 3.0 and up and Internet Explorer 7 and up, and TLS 1.2+ is supported with Android version 5.0 and up and Internet Explorer 11 and up. Any clients below those supported browser versions may have issues connecting to your migrated application. Newer browser clients do not require any changes to work properly.

Multi-Certificates to Single Application: Some users may have configured multiple SSL Endpoints as a way to use more than one certificate with a single app (using empty apps to hold the additional endpoints). Using SSL Endpoints in this way is no longer required. Heroku now supports multiple certificates with a single app as an included platform feature. Domains and certificates should be added on the app that runs the dynos.

Migration Steps:

By following these steps, your application should not encounter any downtime or availability issues

  1. If you have provisioned SSL Endpoints to a free Heroku application, please upgrade to the Heroku Hobby Plan to be able to utilize the Heroku SSL feature and Heroku ACM. Both features will be part of the $7/month “Hobby” plan, saving you $13/month (SSL Endpoint cost is $20/month)

  2. Find the certificates and private key used with your current Heroku SSL SNI Endpoints if you have them, or get new ones. For security reasons Heroku cannot provide the private key currently in use with your SSL Endpoints. See below if you'd like to have your certs automatically managed by Heroku ACM.

  3. Upload the certificates so that they’re ready to use with Heroku SSL SNI endpoints:

    heroku certs:add example.crt example.key --type sni

    which will provide you with the SNI endpoint name such as haiku.herokudns.com

  4. Once this is done, please set the start-ssl-endpoint-dns-migration flag on the SSL endpoint app:

    heroku features:enable start-ssl-endpoint-dns-migration -a [your-app-name]

    We'll proceed to perform DNS migration for the app in the next 24-48 hours. You should receive an email once this is complete. If you don't receive an email in 24-48 hours, please reach out to us via a support ticket.

  5. Update your CNAME target through your DNS provider from the previous SSL Endpoint target such as tokyo-something.herokussl.com or haiku.herokuapp.com (for EU heroku apps) to the SNI Endpoint DNS Target such as haiku.herokudns.com or custom-domain.herokudns.com provided by Heroku SSL. You can find this DNS target with the command:

    heroku domains

  6. Set the start-ssl-endpoint-migration feature flag on the SSL Endpoint app. Please note that the feature name is different from the previous step. This will cause Heroku to initiate the dyno migration:

    heroku features:enable start-ssl-endpoint-migration -a [your-app-name]

    Once you have initiated the migration, this cannot be undone. Contact Heroku Support if you encounter problems

  7. Once you ensure that things are stable, you will need to manually remove the SSL Endpoint associated with the app using:

    heroku addons:destroy ssl

    The add-on will be automatically deprovisioned by Heroku after October 18, 2021.

  8. At this point, you will be fully migrated to updated infrastructure and be able to utilize all of the use-cases of SSL Endpoints through the Heroku SSL Feature, including enforcement of TLS 1.2+.

If you'd rather have your certificates managed by Heroku, enable Heroku ACM with:

heroku certs:auto:enable

If you encounter any issues during manual migration, please visit https://help.heroku.com to troubleshoot or by logging a ticket with the Heroku support team.

Ask on Stack Overflow

Engage with a community of passionate experts to get the answers you need

Ask on Stack Overflow

Heroku Support

Create a support ticket and our support experts will get back to you

Contact Heroku Support