Contact us at |support@ssldragon.com

How to install an SSL Certificate on Heroku?

Friday, January 25th, 2019

In this guide, you will learn how to install an SSL Certificate on Heroku. If you haven’t applied for a certificate yet, the first part will show you how to generate a CSR code for Heroku during the buying process. We’ve also included a bit of Heroku history to satisfy your curiosity, and, finally, a few useful tips on where to buy an SSL certificate for a Heroku server.

Generating CSR on Heroku
Install an SSL Certificate on Heroku
Heroku history and versions
Where to buy an SSL Certificate for Heroku?

Generating CSR on Heroku

CSR (Certificate Signing Request) is a text file you must submit to the Certificate Authority as part of the SSL application process. It contains the required information about domain ownership and your organization. If the CSR details are not correct or out of date, the CA will not sing your certificate.

Since you can’t generate a CSR code directly on Heroku, you have two alternative options. You can use our CSR Generator tool, and it will automatically create the CSR and private key, based on your information. Or, you can generate the CSR on your local environment using OpnSSL, a built-in utility in Apache and Nginx servers.

If you decide on the OpenSSL option, please follow the steps below:

  1. At the prompt, run the following command:
    openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr
  2. Please, replace “server” with the domain name you want to secure
  3. The command will initiate the CSR and private key generation. Now, you’ll be prompted to fill in all the required fields. Use the examples below as a reference:
    • Common Name – type the Fully Qualified Domain Name (FQDN) you want to protect. For instance, ssldragon.com

      Note: If you’re generating a CSR for a wildcard certificate, add an asterisk in front of your domain name. For example, *.ssldragon.com.

    • Country – enter the two-letter country code. If you’re registering an organization, make sure to provide the country of its legal origin. (e.g. US)
    • State or Province – specify the state or region where your company is legally located (e.g. Nevada)
    • City – name the city where your business is legally registered (e.g. Las Vegas)
    • Organization – submit the legal name your organization. For instance, GPI Holding LLC. For Domain Validation Certificates, submit NA
    • Organizational Unit – specify the department in charge of SSL management. For example, IT. If you have a DV certificate, enter NA
    • E-mail address – provide a valid email address
  4. Once you’ve completed all the required information, you should have your CSR code (.csr file) and private key (.key file) in the folder when you ran the command
  5. Next, open the .csr file with any text editor and copy the whole text, including the —–BEGIN NEW CERTIFICATE REQUEST—– and —–END NEW CERTIFICATE REQUEST—– tags (you can use ctrl + a hotkey to select the entire text) and paste it during your SSL order process with SSL Dragon
  6. Back up the .key file. You will need it during the SSL installation.

Now, you have to wait until the CA verifies and validates your SSL request. Depending on the type of certificate, the process may take between a couple of minutes and 7 business days. Once you’ve received the certificate files in your inbox, continue with the installation steps.

Install an SSL Certificate on Heroku

In the past, you had to purchase the SSL Endpoint add-on for your app, worth $20 per month, to install an SSL certificate on Heroku. Today, HerokuSSL, a new free feature available under Heroku paid plans, allows you to manage SSL/TLS encryption for custom domains.

SSL Endpoints are still available for legacy clients and browsers compatibility. Below, you’ll find installation instructions for both Heroku SSL and SSL Endpoint.

Prepare all your SSL Certificate files:

After your Certificate Authority validates your SSL request, you’ll receive all the necessary files in your inbox. To successfully install an SSL cert on Heroku you need the following files:

  • The main certificate file, usually with the .crt extension
  • The CA Bundle file, containing the root and intermediate certificates
  • The private key file, generated along with the CSR on the same server

Install an SSL certificate on HerokuSSL

Please note that for Heroku you need to combine the primary certificate and the CA Bundle into a single file. You can do it manually by opening the .crt and .ca-bundle files with any plain text editor and pasting the contents from the .ca-bundle file just below the contents in the .crt.file. Make sure there are no spaces between the codes.

Alternatively, via the command line, you can combine the files using the following command:

cat yourcertificate.crt bundle.ca-bundle > server.crt

You can install your certificate on HerokuSSL via the Dashboard or CLI. Select your preferable method.

Via Heroku Dashboard

    1. Open the Certificate
    2. Select the necessary application from the list, then select Settings
    3. Scroll down the page and in the Domains and certificates section click on Configure SSL
    4. A new window will appear on your screen. From the options presented, select Manually and click Continue
    5. Now you have to drag and drop the combined certificate and CA bundle file to the first box and click Continue. In the second box, upload your Private Key file. Heroku will prompt you to update the DNS records of your custom domain/subdomain.

Here, you need to create a CNAME record using the values shown to you.

  • The Host value (‘Name’, etc.) is your domain/subdomain
  • The Target value (‘Points to’, etc.) is yourdomain/subdomain.herokudns.com.

Example: yourdomain.com CNAME yourdomain.com.herokudns.com or www.yourdomain.com CNAME www.yourdomain.com.herokudns.com

Once you’ve configured the DNS, click on I’ve done this and then click on Continue. Please note that it may take a while before DNS is updated globally.

Congrats, your domain is now secured with an SSL certificate.

Via Heroku CLI

Use the following command to upload the combined certificate plus CA Bundle file and the Private key:

heroku certs:add server.crt server.key

If there isn’t a default Heroku app, you need to specify it as well using the —app flag. Here’s the command for that:

heroku certs:add server.crt server.key --app yourappname.

Check if the correct certificate is installed:

heroku certs:info

Note: If you receive an “Internal server error” message when uploading your certificate the reason may be an outdated Heroku CLI version. To fix the error, you’ll need to update the CLI version.

Install the SSL certificate on SSL Endpoint

  1. First, you need to create an SSL Endpoint. At the prompt, in your local environment run the following command:
    $ heroku addons:create ssl:endpoint
  2. Now, you have to upload the .crt file in the same SSL directory of your application, and then merge the main certificate with the CA bundle certificates into a single file. To combine the certificate files, use the command below:
    $ cat example.crt bundle.crt > server.crt
  3. Your next step is to import the private key and certificate to the endpoint via the command below:
    $ cat example.crt bundle.crt > server.crt
  4. The output will display the details of your SSL certificate and the hostname selected for your SSL endpoint
    Adding SSL Endpoint to example… done
    example now served by example-2121.herokussl.com.
    Certificate details:
    Expires at:
    Issuer:
    Starts at:

    Note: The endpoint creation may take up to 30 minutes (or in rare cases up to 2 hours).

  5. Once your endpoint is ready, you need to reroute requests for your protected domain to the Heroku endpoint hostname. If you haven’t added the domain to your app yet, run the following command to do it now:
    $ heroku domains:add www.example.com
    Adding www.example.com to example… done
  6. To reroute requests to the endpoint hostname, create a CNAME record. Don’t forget to replace “example” with the relevant information.
    • Record type – CNAME
    • Name – www
    • Target – example-2121.herokussl.com
      For Wildcard Certificates create a similar record:
    • Record type – CNAME
    • Name – *
    • Target – example-2121.herokussl.com

If you set a CNAME record for the root (@) domain, it will overwrite all the other records that you set up for the domain. To create a CNAME for a subdomain, your certificate must cover the subdomain (www.example.com, subdomain.example.com, *.example.com).

You can set up a certificate issued for a bare domain (example.com) only if your DNS provider offers CNAME-like functionality at the zone apex.

When buying an SSL Certificate pay close attention to its specifications. Some certificates don’t support both with and without “www” feature.

That’s it for the Heroku SSL installation. It’s always worth it to check your SSL certificate for potential errors right after the configuration. Use these excellent SSL tools to get instant status reports and vulnerability alerts.

Heroku history and versions

Heroku is one of the oldest cloud platforms, in development since 2007. Initially, Heroku supported only Ruby programming language, but today it’s a polyglot platform, allowing developers to build, run and scale applications in Java, Scala, Node.js, Clojure, PHP, GO, and Python. Heroku is a subsidiary to Salesforce.com, an American cloud company, based in California. In 2010, Salesforce acquired Heroku for $212 million. The name “Heroku” is a portmanteau of “heroic” and “haiku”. The Japanese reference is an acknowledgment to Yukihiro Matsumoto, also known as Matz for creating Ruby.

Below you’ll find the latest application releases supported by Heroku:

Java

  • Java 7 – 1.7.0_181
  • Java 8 – 1.8.0_181
  • Java 9 – 9.0.4
  • Java 10 – 10.0.2
  • Java 11 – 11

Node.js

  • Currently supported releases are 6.x, 8.x, 9.x, and 10.x

Clojure

  • Any production version of Clojure, running on a supported JDK release

PHP

  • PHP 5.6 (64-bit), PHP 7.0 (64-bit), PHP 7.1 (64-bit), or PHP 7.2 (64-bit)

Python

Supported runtimes:

  • python-3.7.0 on all (cedar-14, heroku-16, and heroku-18) runtime stacks
  • python-3.6.6 on all (cedar-14, heroku-16, and heroku-18) runtime stacks
  • python-2.7.15 on all (cedar-14, heroku-16, and heroku-18) runtime stacks

Where to buy an SSL Certificate for Heroku?

When buying an SSL Certificate, you should pay attention to three crucial aspects: validation type, price, and flawless customer service. At SSL Dragon, we deliver them all! Our SSL certificates are signed by renowned Certificate Authorities, and thus are compatible with the majority of cloud platforms, including Heroku. Whether you need a cheap Domain Validation certificate or a premium Extended Validation product we’ve got you covered. Here’s our full list of SSL certificate types:

SSL Dragon’s prices are the most competitive on the market, while our dedicated support team is highly appreciated by the existing customers. If you don’t know what type of SSL certificate to choose, simply use our SSL Wizard and Certificate Filter tools. They will help you find the ideal SSL product for your website.

If you find any inaccuracies, or you have details to add to these SSL installation instructions, please feel free to send us your feedback at [email protected]. Your input would be greatly appreciated! Thank you.