If you’re building an application that needs to go into production, you’ll undoubtedly need to serve it securely using SSL. What this entails varies from provider to provider, and you’ll encounter different levels of complexity (and cost) in setting it up.
Fortunately, if you’re using Heroku to run your app, this is pretty easy. Since I recently gave Heroku another shot, I’ll devote this article to going over what you’ll need to run SSL on the platform and why you might choose some features over others.
What does Heroku provide for SSL out of the box?
Heroku focuses on ease of use and I like that. Whether it’s a one-click deployment straight from my GitHub repo or a plugin ecosystem that lets me drop all kinds of cool stuff into my app from the command line, I always appreciate the out-of-the-box options I have at my fingertips . Likewise, SSL on Heroku provides some great default options.
Heroku offers two main ways of working with SSL certificates on its platform:
- Automated Certificate Management (ACM)
- Heroku SSL
For most applications, ACM will give you a really simple, automated certificate management experience – that’s the name, after all. But sometimes you’ll need a more robust Heroku SSL option. We’ll look at ACM first. Next, we’ll explore why you would need Heroku SSL and how you would use it.
Automated certificate management and how it works
ACM is built on top of Let’s Encrypt—a free, automated certificate authority, operated by a non-profit organization dedicated to improving web security in general. Although organizations can sponsor the Let’s Encrypt project, there is no cost to use SSL certificates issued by Let’s Encrypt. Since certificates are free, Heroku offers automated certificate management with any of its basic plans at no additional cost.
While Let’s Encrypt automates the process of requesting and issuing certificates, ACM automates the process of installing those certificates on the relevant applications for the domains for which they were issued. There are other methods for automated certificate management, but they are paid plugins, so I won’t cover them here. Instead, let’s show you how to add ACM to a demo app I’ve already deployed on Heroku.
To be clear, you don’t need to configure much for ACM. In fact, if you haven’t added a custom domain to your app, the URL generated by Heroku (on the herokuapp.com domain) for your app already has SSL.
Step 1: Enable ACM
Your first step is to turn on ACM. The easiest way to do this for any deployed application is with the Heroku CLI. Assuming you’re logged into Heroku via the CLI, all you need to do is run a single command to enable ACM:
$ heroku certs:auto:enable
Enabling Automatic Certificate Management... starting.
See status with heroku certs:auto or wait until active with
heroku certs:auto --wait
=== Your certificate will now be managed by Heroku.
Check the status by running heroku certs:auto.If you enable ACM before setting up a custom domain in your application, you’ll get a message like this:
$ heroku certs:auto
=== Automatic Certificate Management is enabled on pure-brushlands-82324
=== Add a custom domain to your app by running: heroku domains:add <yourdomain.com>Step 2: Add a custom domain
At this point you just need to do what the Heroku CLI says and add the domain to your app. You can also do this in the CLI.
$ heroku domains:add really-cool-stuff.app
Configure your app's DNS provider to point to the DNS Target lively-basin-0v9xkh99iaz1yc0xldmakla5.herokudns.com.
For help, see https://devcenter.heroku.com/articles/custom-domains
The domain really-cool-stuff.app has been enqueued for addition
Run heroku domains:wait 'really-cool-stuff.app' to wait for completion
Adding really-cool-stuff.app to ⬢ pure-brushlands-82324... done
Step 3: Configure DNS
At this point you need to update your DNS records on your domain to point to the DNS target provided by Heroku. The instructions in the linked help documentation are detailed and clear. Usually this means adding a CNAME record that points to the new location that it provides to Heroku.
Once you have configured DNS correctly, you can check the status of your certificates. You should see output like this:
$ heroku certs:auto
=== Automatic Certificate Management is enabled on pure-brushlands-82324
Certificate details:
Common Name(s): really-cool-stuff.app
Domain(s): fe6ab605-91f9-4261-974c-ee85c043dbf7
Expires At: 2024-05-27 17:08 UTC
Issuer: /CN=R3/O=Let's Encrypt/C=US
Starts At: 2024-02-27 17:09 UTC
Subject: /CN=really-cool-stuff.app
SSL certificate is verified by a root authority.
Domain Status Last Updated
─────────────────────────── ─────────── ────────────
really-cool-stuff.app Cert issued 4 minutesIf you’re like me and you made a mistake while setting up your DNS records… you might see some warnings on the application dashboard in the web interface like this:
Or this one:
Fortunately, ACM regularly repeats its validation attempts throughout the hour. So, I was able to quickly solve my problems. I got to green status pretty easily.
If you’ve ever had to set up SSL on another platform before, you’re probably painfully aware that it’s usually not that simple (and that’s putting it mildly). That said, Let’s Encrypt has some limitations that may require you to use a more robust offering: Heroku SSL.
Heroku SSL and why you would want it
While ACM gives you a really simple experience, with that simplicity comes somewhat limited functionality. Let’s consider two examples where ACM may not meet your unique needs.
Example 1: When you need replacement certificates
Let’s Encrypt is limited to issuing common name certificates in only one domain name zone. Sometimes you might want to have a replacement certificate; this is the kind of functionality you might need if you have a multi-tenant application that switches between tenants at the subdomain level. ACM does not support this. But Heroku SSL does.
Example 2: When you need organizational or extended validation (OV/EV)
Let’s Encrypt also does not guarantee that you are who you say you are. What I’m trying to say is that the type of certificate issued by Let’s Encrypt only verifies that the entity requesting the certificate also controls the domain name it’s securing. There are some scenarios when you need to ensure more than just your domain traffic when transferring. You may need to verify that your application is actually associated with your company. In this case, you should purchase an SSL certificate with Organizational Validation (OV) or Extended Validation (EV). These typically require checks that cannot be easily automated using a product like Let’s Encrypt.
Using Heroku SSL
In the above cases, you will need to upload your own certificate manually. As usual, Heroku has simplified this process beautifully (but it’s still more work than just telling the platform to start issuing certificates with ACM).
To add or update a certificate for your Heroku app and use the certificate you provided, you need to run a single command:
$ heroku certs:add server.crt server.key
Adding SSL to example... done
exampleapp now served by exemplary-sushi-4gr7rb6h8djkvo9j5zf16mfp.herokudns.com.
Certificate details:
Expires At: 2022-08-18 21:53:18 GMT
Issuer: C=US; ST=CA; L=SF; O=Heroku; CN=www.example.com
Starts At: 2021-08-18 21:53:18 GMT
...Ok, so it’s not that a lot more work than using ACM.
Note that you cannot add multiple intermediate certificates to make a valid chain against any root certificate that signed your new certificate. However, you can merge your intermediate certificates into a single file so that they can be transferred as a single file.
After uploading the certificate via Heroku SSL, you will be able to see your application protected by your self-provided SSL certificate. While Heroku SSL still makes things pretty simple, keep that in mind you are responsible for keeping your certificates up to date. You will also need knowledge of how to work with certificates. While this may not bother you, these are important points to remember—especially when you consider that ACM takes care of automatically renewing SSL certificates. With ACM, simple setup commands are essentially “set it and forget it.” However, Heroku has designed its entire certificate management system in such a way that even if you need the most advanced options, it’s still very simple and manageable, even if you don’t have much experience with certificates.
Conclusion
While there is more you can do with SSL on Heroku, both the ACM and Heroku SSL options can provide functionality to suit most use cases. Heroku’s documentation in this space also provides enough detail to point you in the right direction. If you haven’t secured your application with SSL (shame on you!), the simplicity of ACM should remove any excuses for needing to properly secure your site. If your use case is more complicated, then Heroku SSL should give you what you need.