Manually Acquiring an SSL/TLS Certificate
Last updated September 30, 2024
By default, Heroku provides free Automated Certificate Management (ACM) for all applications. If you want to use a different certificate authority for your application or a wildcard certificate on a Private Space app, follow these steps to acquire a certificate manually.
Purchasing an SSL certificate varies in cost and process depending on the vendor. ExpeditedSSL and SSL FastTrack offer simple ways to purchase a certificate and are recommended solutions. Using other SSL providers will require some or all of the following steps.
Generate private key
Before requesting an SSL cert, generate a private key in your local environment using the openssl tool. If you cannot execute the openssl command from the terminal you may need to install it.
| If you have… | Install with… |
|---|---|
| Mac OS X | Homebrew: brew install openssl |
| Windows | Windows complete package .exe installer |
| Ubuntu Linux | apt-get install openssl |
Use openssl to generate a new private key.
When prompted, enter an easy password value as it will only be used when generating the CSR and not by your app at runtime.
Heroku only supports RSA keys for certs. Elliptic curve keys are not supported.
$ openssl genrsa -des3 -out server.pass.key 2048
...
Enter pass phrase for server.pass.key:
Verifying - Enter pass phrase for server.pass.key:
The private key needs to be stripped of its password so it can be loaded without manually entering the password.
$ openssl rsa -in server.pass.key -out server.key
You now have a server.key private key file in your current working directory.
Generate CSR
A CSR is a certificate signing request and is also required when purchasing an SSL cert. Using the private key from the previous step, generate the CSR. This will require you to enter identifying information about your organization and domain.
Though most fields are self-explanatory, pay close attention to the following:
| Field | Description |
|---|---|
| Country Name | The two letter code, in ISO 3166-1 format, of the country in which your organization is based. |
| Common Name | This is the fully qualified domain name that you wish to secure.
|
The Common Name field must match the secure domain. You cannot purchase a certificate for the root domain, (for example, example.com), and expect to secure www.example.com. The inverse is also true.
Generate the CSR:
$ openssl req -nodes -new -key server.key -out server.csr
...
Country Name (2 letter code) [AU]:US
Common Name (eg, YOUR name) []:www.example.com
...
The result of this operation will be a server.csr file in your local directory (alongside the server.key private key file from the previous step).
Submit CSR to SSL provider
Next, begin the process of creating a new SSL certificate with your chosen certificate provider. This will vary depending on your provider, but at some point you will need to upload the CSR generated in the previous step.
You may also be asked for what web server to create the certificate. If so, select Nginx as the web server for use on Heroku. If Nginx is not an option, Apache 2.x will also suffice.
If you’re given an option of what certificate format to use, such as PKCS or X.509, choose X.509.
If you want to secure more than one subdomain you will need to purchase a wildcard certificate from your provider. While these certificates are typically more expensive, they allow you to serve requests for all subdomains of *.example.com over SSL.
On completion of the SSL certificate purchase process you should have several files including:
- The SSL certificate for the domain specified in your CSR, downloaded from your certificate provider. This file will have either a
.pemor.crtextension. - The private key you generated in the first step,
server.key.