API calls from a Rails App on Heroku Pt. 2: Adding an SSL

In the process of being a one-man developer show, don’t we find that the time we spend actually coding is only part of the process? You have to come up with a decent design, code the “thing”, and then do some DevOps when you deploy the said, “thing”. Sometimes we can get stuck down the rabbit hole of researching how to accomplish these tasks.

In this article, we will talk about how to add an SSL to your Rails API endpoint when it is hosted on Heroku.

Why Add An SSL?

As mentioned in part 1 of this series, if you using a Rails API as an intermediary or gateway between your frontend and a third-party API, and this backend is hosted on Heroku, then you will need to ensure the following:

  1. You have a custom domain address for your Rails API
  2. The Rails API endpoint is HTTPS

So let take on the first step in this process: Configuring your custom URL with Heroku.

Add Custom URL To Heroku

There are many services where you can purchase a custom domain. I used Name.com, and so this section will have that in mind, but most everything should apply to other services.

First, you want to navigate your Heroku project console’s setting tab. You should see a section on adding a custom domain that looks like this.

You then will need to add your domain. An explicit example would be something like: mybackendapi.com. Heroku will then generate a DNS target that you will need to use with the domain provider.

Navigate to the page where you manage the DNS records for your domain. You should see an area where you can add DNS records. You will notice the inputs: Type, Host, Answer, TTL. Try providing the following details.

Type: CNAME
Host: (blank)
Answer: (DNS target from Heroku)
TTL: 300

After doing this your Heroku project should successfully be pointing to your new custom domain. If it isn’t right away, you may need to give it some time for it to process.

Important!
The www prefix will still not work at this point. Repeat the steps in this sub-heading, but with the www prefix prepended when adding the domain to Heroku. When adding the new DNS record to the domain provider, input “www” under the Host field.

The SSL Rabbit Hole

Before continuing on this guide I must inform you that there are two ways to proceed from here in adding an SSL to your Heroku project. There is an automatic way that requires probably less than a minute. The manual way or more time-consuming way is more educational. When automation fails, as it sometimes does, it is good to know how to drive the ol’ stick shift. As you might have also guessed, I discovered to hard way before discovering the easy way, hence “The Rabbit Hole”.

The Automatic Way To Generate An SSL

Once you successfully have your custom domain working, you need to make the endpoint secure. We are talking about HTTPS!

To do this on Heroku you have to upgrade to their Hobby dyno. Their built-in Automatic Certificate Management will take care of the rest!

I told you it was easy…

The Manual Way To Generate An SSL

The manual way would not be such if it did not involve the command line, so break out your terminal and get ready!

First, go to the root directory of your project. The directory where you would normally heroku login . You need to generate a server.pass.key. Enter an easy password for later when prompted.

openssl genrsa -des3 -out server.pass.key 2048

Now you will create a server.key file. Enter in the password from earlier when prompted.

openssl rsa -in server.pass.key -out server.key

You are now ready to generate the server.csr. The CSR will be needed to generate your SSL certificate.

openssl req -nodes -new -key server.key -out server.csr

Specific information is needed to generate the CSR. For individuals, it is ok to put their name under Organization Name. Under Common Name, make sure to put your domain. Also, notice which fields were left blank. This is totally fine if it does not apply.

Provide theserver.csr to your SSL provider to receive your SSL certificate. This may take a few hours for them to get back to you.

Once you receive the SSL certificate you want to create a file in the root directory called server.crt and paste the SSL there. If you received intermediary and root certificates as well, then similarly create intermediary.crt and root.crt in the root directory.

Now you want to add the SSL certificate to your project. This command checks that the server.key is the same key that was used to generate the CSR, before adding the SSL to the project.

heroku certs:add server.crt server.key

As an option, you may provide the intermediary.crt for better compatibility with older browsers.

heroku certs:add intermediary.crt server.crt server.key

Make sure to keep all of these files safe for later use and you should be good to go.

Final Words

So the easy way or the hard way? Whichever one you pick is up to you. I went down the Rabbit Hole myself and am happy I learned something. Hope it helps!

Sources:
https://devcenter.heroku.com/articles/acquiring-an-ssl-certificate
https://devcenter.heroku.com/articles/ssl

Full-Stack Software Engineer and Lifelong Learner