Have a question or solution? Post it at the SSL.com IT Security Q&A community site. All visitors welcome and it's FREE!

SSL Installation Support

Knowledge base and troubleshooting guides for ssl installation issues

Install SSL Certificate on Heroku
Posted by Leonard Grove on 24 October 2012 05:32 PM

SSL is a cryptographic protocol that provides end-to-end data encryption and data integrity for all web requests. Apps that transmit sensitive data should enable SSL to ensure all information is transmitted securely.

Piggyback SSL

You can access any Heroku app over SSL at: https://myapp.heroku.com/ or https://myapp.herokuapp.com/ depending on the stack used.

An app-specific SSL certificate is not required for Piggyback SSL. The *.heroku.com and *.herokuapp.com wildcard SSL certificates are used for all apps. You can view information about the *.heroku.com certificate by visiting https://www.heroku.com/ and clicking the lock icon in your browser.

Custom-domain SSL

Heroku all provides SSL for your custom domain, e.g www.yourdomain.com, with our SSL Endpoint add-on.

The steps for setting up custom domain SSL with your Heroku app are as follows

  1. Acquire SSL certificate
  2. Install the SSL Endpoint add-on
  3. Add the cert it to your application
  4. Configure DNS

Acquire SSL certificate

All custom domain SSL options require generating an SSL certificate. If prompted during the SSL certificate process, specify the Apache 2.x web-server.

You must also remove the passphrase from your certificate so Heroku can automatically load it on your behalf (do this before adding your chain or intermediate certificate):

$ mv server.key server.orig.key
$ openssl rsa -in server.orig.key -out server.key

For testing, use these instructions to generate a self-signed certificate. In production, to remove the warnings, you will need to purchase an SSL certificate.

Add your SSL add-on

$ heroku addons:add ssl
Adding ssl on myapp... done, v1 ($20/mo)
Next add your certificate with: heroku certs:add PEM KEY
Use `heroku addons:docs ssl` to view documentation.

This enables your app to use the certs command to manage your SSL endpoint.

Add the certificate to your app

The certs command for the SSL Endpoint command is available in the Heroku client version v2.25.0 and up. If the command is not available please upgrade your Heroku client version.

Using the certificate you generated in the previous step, upload it to Heroku:

$ heroku certs:add server.crt server.key
Added certificate to www.yourdomain.com, expiring in 2012/08/27 22:16:39 -0700

Configure DNS

Next, add a CNAME record in the DNS configuration that points from the domain name that will host secure traffic e.g. www.mydomain.com to the SSL endpoint hostname, e.g. tokyo-2121.herokussl.com. Consult your DNS provider for instructions on how to do this. The target should be the fully qualified domain name for the SSL endpoint associated with the domain.

Legacy SSL add-ons

Documentation for the legacy SSL add-ons, ssl:hostname, ssl:sni and ssl:ip can be found here. If you are using one of these add-ons, consider upgrading to SSL Endpoint (see next section). The legacy add-ons have been deprecated in favor of ssl:endpoint and will be fully replaced in the future:

  • ssl:hostname is directly replaced by ssl:endpoint. The feature set for ssl:endpoint is a superset of ssl:hostname.
  • ssl:sni will not be supported on the Cedar stack and thus will naturally be phased out as apps are migrated to the Cedar stack.
  • ssl:ip has serious availability and uptime implications. Its use has been discouraged for some time.

Upgrade from legacy SSL add-ons

It is straightforward to upgrade to SSL Endpoint from a legacy SSL add-on. No downtime is required.

Start by adding ssl:endpoint to your app:

$ heroku addons:add ssl:endpoint --app myapp
Adding ssl:endpoint to myapp... done

Now upload the same certificate and private key that you are currently using on the existing SSL setup:

$ heroku certs:add my_existing.crt my_existing.key --app myapp
Adding certificate to myapp... done
myapp now served by tokyo-2121.herokussl.com.

Your new endpoint is now ready to receive traffic. To direct traffic to the endpoint, go to your DNS provider and update the records for your domain so that you have a single CNAME entry pointing to the SSL endpoint host (e.g. tokyo-2121.herokussl.com).

Once the DNS change propagates, your users will be routed to the new endpoint. You can de-provision the old SSL add-on, for example:

$ heroku addons:remove ssl:hostname --app myapp
Removing ssl:hostname from myapp... done
original reference: https://devcenter.heroku.com/articles/ssl#customdomain-ssl
(7 votes)
This article was helpful
This article was not helpful

Comments (0)
Post a new comment 
Full Name:
CAPTCHA Verification 
Please enter the text you see in the image into the textbox below. This is required to prevent automated registrations and form submissions.