Mittwoch, 9. Mai 2012

Setting up SSL on Heroku

Recently i bought an Thawte SSL certificate for my Heroku application, and i thought it would be useful for you if i wrote down my „how to do“ cook book to get it up and running.
By the way. I'm a Mac user, so for Windows there could be slightly differences...

Please note, that www.domain.com is a placeholder for your domain.

1. Generate a Private Key

-> openssl md5 * > rand.dat
-> openssl genrsa -rand rand.dat -des 2048 > www.domain.com.key
Now you are asked to enter a pass phrase.
Please remember the phrase well, you will need it later!

2. Create a CSR

To be able to order a certificate, you have to supply some information. That bundle of information is called an Certificate Signing Request (CSR).

You generate it using your recently generated key, with the command below.

-> openssl req -new -key www.domain.com.key -out www.domain.com.csr

Now you are asked to enter your pass phrase, entered in step 1 above.
Further more, you have to answer the questions asked:
- Two letter country code: DE (for Germany e.g.)
- State or Province: Bavaria (e.g.)
- Locality Name (e.g. city): Gerbrunn
- Organization Name (e.g. company): Company Ltd (e.g.)
- Organizational Unit Name (e.g. section): CEO
- Common Name (the domain name used with the SSL cert.): www.domain.com
- Email Address: foo@fie.com

'extra' attributes to be sent with the certificate request
- A challenge password: (just return to leave empty)
- An optional company name: (just return to leave empty)

Please note, that according to what certificate you want to order, the data entered here must be the same as in the whois record for the domain. In my case, ordering the certificate "Limitbreaker" provided by http://www.psw.net that wasn't necessary

3. Order a certificate

Copy the content of the www.domain.com.csr to your clipboard, and paste it into the order form.
For mac users. This command transfers the content of the file into the clipboard:
-> pbcopy < www.domain.com.csr

(Hint: "pbpaste > file.txt" is the opposit command ;-)

You can check you CSR here:
https://secure.comodo.net/utilities/decodeCSR.html

When you have gotten the certificate (my mail or download), save it in the file www.domain.com.crt

The certificate that i acquired by Thawte also has an intermediate certificate, that has to be installed in order for the certificate to function properly.
Save that in the file: www.domain.com.intermediate.crt

To keep older browser and mobile devices support, i ALSO had to install the Thawte Cross Root CA Certificate (as additional intermediate certificate).
 Save that in the file www.domain.com.crossroot.crt

Now use a simple and pure text editor to combine all three certificates in one file.
The content of the new file should look like this:

-----BEGIN CERTIFICATE-----
... content of the file www.domain.com.crt ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... content of the file www.domain.com.intermediate.crt ...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... content of the file www.domain.com.crossroot.crt ...
-----END CERTIFICATE-----

Save this in the file www.domain.com.all.crt

4. Remove passphrase from key

Later on we need the generated key without the pass phrase, so we have to remove it here:

-> openssl rsa -in www.domain.com.key -out www.domain.com.no_pass.key

Now you have to enter the pass phrase again, and you get the answer: "writing RSA key"

5. Add the Heroku SSL Addon "SSL"

What Heroku SSL service you choose, depends on what you need and on what stack your app is runnig. My app is unfortunately running on the cedar stack, so i have to choose the Endpoint SSL.
(I dont understand, why that cost $20,- / month.)

You add the ssl addon with this command, in the root directory of your project:

-> heroku addons:add ssl:endpoint

6. Add the certificate to your app on Heroku

Copy the files www.domain.com.all.crt and www.domain.com.no_pass.key to your project root directory and enter the command:

-> heroku ssl:add www.domain.com.all.crt www.domain.com.no_pass.key

Update:
Now, as the ssl:endpoint has gon "main stream" on the cedar stack, you add the certificate using this command:
-> heroku certs:add www.domain.com.all.crt www.domain.com.no_pass.key  

7. Check

This Heroku command lists some usefull commands:

-> heroku ssl --help

To get the ssl info for your application, just type this command in the root directory of your project:

-> heroku ssl

8. Self signed Certificate

If you have any problems, you could check if everything else is ok, by creating a self signed certificate.
There exist a Heroku docu on that:

Here are the steps taken from the Heroku doku:
Generate Key:
-> genrsa -des3 -out site.key 2048

Copy key:
-> mv site.key site.orig.key

Remove pass phrase from key:
-> openssl rsa -in site.orig.key -out site.key

Create CSR:
-> openssl req -new -key site.key -out site.csr

Create Certificate:
-> openssl x509 -req -days 365 -in site.csr -signkey site.key -out final.crt

Install on Heroku:
-> cd [root directory of your project]
-> heroku ssl:add final.crt site.key

9. Further reading

Regarding file name extensions:
https://devcenter.heroku.com/articles/ssl-file-extensions

Have fun!
Comments and hints are welcome.

Kommentare:

  1. Thanks for this HowTo, very useful.
    Which "server platform" did you specify when buying your certificate from Thawte ?

    AntwortenLöschen
    Antworten
    1. Hi!

      I bought my cert here (the Limitbreaker):
      http://www.psw.net/ssl-zertifikate.cfm

      And i didn't have to specify any server platform. As far as im concerned, the certs are "universal".

      Best regards and a happy new year!

      Löschen
  2. Dieser Kommentar wurde vom Autor entfernt.

    AntwortenLöschen