We’re working on a new back-end to support our visualizations of personal data from services like Twitter, Facebook and LinkedIn. These services now routinely offer https, the secure form of http, as an option to protect users from eavesdropping on open networks. It took a high profile release of a simple tool, FireSheep, to give users the awareness to activate this by default, and many users still aren’t aware that they need to do it. A few months later, https is “table stakes” for online services that handle personal data and it makes sense to activate it in new products by default. For example, your server must support https if you want to use Foursquare’s new push APIs or display content on Facebook after October 1st. Other services will surely follow suit.
If like me you’ve never needed to activate https you might not know what’s involved or what to look for. I’m still learning, but I thought I’d share what I’ve found so far.
To enable https you need to make sure your web server host supports it and you need an SSL certificate. SSL certificates are “just” text files of data that represent a chain of trust from a certificate authority through the certificate seller and down to you. The certificate authority’s credentials are installed in your browser to allow it to verify the certificates of websites you visit. Ideally there are identity checks at all stages of the certification process, though in practice it’s probably just an automated phone message and an email by the time it gets to you. Of course you need a credit card to pay for a certificate; those are table stakes too.
SSL on Heroku
We’re using Heroku for our hosting and they support a few different options for SSL in their add-ons section. If you’re using a *.heroku.com or *.herokuapp.com domain for your app you can just activate “piggy-back” SSL for free and stop reading. I’m told by support that this will be activated by default for new apps and that it definitely supports the new herokuapp.com Cedar stack, which wasn’t clear from the add-on page.
Otherwise, the differences between SSL options are fairly well explained on the SSL add-on page and from Heroku’s perspective it’s a matter of pushing you towards solutions that are most compatible with cloud hosting. Securing every subdomain is usually what you want, but in the cloud this means a dedicated IP address for your domain and you will be charged accordingly. We went with hostname SSL, which is a bit more convenient in the cloud but still requires a load balancer step, so Heroku currently charges $20/month for this option. Hostname SSL enables us to secure a single subdomain like secure.example.com.
Note: if you’re using Heroku their graphical tools are beautifully designed but not especially feature-complete, especially for SSL. It’s better to jump straight to the technical documentation and complete tasks on the command line. Their documentation for SSL support is clear and up-to-date.
Choosing a Provider
After asking around we received a couple of recommendations for an SSL certificate. Most useful articles you’ll find with Google talk about using GoDaddy but we’re not big fans of their up-sell process or tools so we wanted to try another seller. Gandi.net looked good but wouldn’t support our .io domain name, so we went with RapidSSL.
The main thing we were looking for was straight-talk and focus, which is why we chose RapidSSL. Our DNS provider also sells SSL certificates but their documentation seemed out of date and links to help documents were broken. But if you like one of your existing providers then of course check with them first.
Note: RapidSSL is an entry-level reseller of certificates from GeoTrust. If you’re not on a budget, or you want Extended Validation which will show your name in the address bar in modern browsers, then go directly to GeoTrust and pay a little bit more. We’re not conducting credit card transactions and our API traffic is largely behind the scenes, so we’re more interested in privacy and security than user experience at the moment.
Making a key and Certificate Signing Request
To acquire an SSL certificate you need to create a private key for your server and use it to create a Certificate Signing Request which you upload during the purchase process.
Heroku uses Nginx to serve your pages (no matter which language you’re using to serve responses, Nginx sees the requests first and forwards them to your app). RapidSSL didn’t have instructions for creating a key/CSR for Nginx but the instructions for Apache worked fine. I used the openssl command in my Mac terminal, as follows:
- Generate a new key with
openssl genrsa -des3 -out example.com.key 2048
- Generate a CSR with
openssl req -new -key example.com.key -out example.com.csr
– note that Common Name will be the name of the subdomain you’re securing.
- Copy/paste the CSR into RapidSSL’s form as part of the purchase process
- Complete the phone confirmation step. I also needed to activate a new forwarding email address on our domain to handle the admin email, because our .io domain couldn’t provide the relevant admin contacts automatically.
- Await your certificates by email. This wasn’t as rapid as we’d hoped, it took about an hour.
- A web server usually requires an unlocked key, so do
openssl rsa -in example.com.key -out example.com.unlocked.key
to create that. With hindsight you could leave out the -des3 in step one and skip this step.
- Save the keys you receive by email. For filenames we used example.com.crt for ours and intermediate.crt for the certificate authority’s certificate.
- Combine your key and the intermediate key using
cat example.com.crt intermediate.crt > example.com.pem
(.pem and .crt seem to be used interchangeably, please let us know if this is incorrect).
- Upload the certificate and unlocked key to Heroku for your app:
heroku ssl:add example.com.pem example.com.unlocked.key --app example-app
- Activate Hostname SSL, and consent to being charged $20/month:
heroku addons:add ssl:hostname --app example-app
- Lastly, update the CNAME DNS record for your subdomain to point to the new hostname provided to you in an email from Heroku. This arrived as quickly as I could check my email.
That’s it! Phewf! A simple 11-step process. There’s a full transcript of this on github if you want to see what the responses look like, and once you have a certificate Heroku’s SSL docs are excellent. Good luck!