Clarify how to provide intermediate certificates with heroku certs:add

[edmorley]

Currently the UX for adding a certificate plus its intermediates is slightly confusing, since:

• the heroku certs:add help text (see below) doesn't mention how to specify the intermediates at all, and uses a CRT reference that could lead people to think that .pem files aren't also accepted.
• the devcenter SSL docs here use a wording ("Add your certificate, any intermediate certificates bundles, and private key with the certs:add command.") that implies that the intermediates should be in a separate certificate bundle (possibly passed as a third argument), when they should in fact be concatenated with the main certificate.
• several third-party guides incorrectly say to pass the intermediates as an additional argument (when there are only two arguments allowed: source), eg:
  • https://lostechies.com/derickbailey/2014/02/12/heroku-and-ssl-fixing-this-sites-security-certificate-is-not-trusted-on-android-and-other-devices/
  • https://gist.github.com/cjolly/3165095#gistcomment-887392
  • https://stackoverflow.com/questions/26076559/renewing-ssl-certificate-on-heroku

It looks like I wasn't the only one who wasn't sure what to do with the intermediate cert:
https://stackoverflow.com/questions/38447944/heroku-ssl-install-intermediate-cert
https://stackoverflow.com/questions/23763411/uploading-ssl-certificate-to-heroku

And a number of guides have popped up to try and document it:
http://www.joshwright.com/tips/setup-a-godaddy-ssl-certificate-on-heroku ("Here's the part that the Heroku docs don't explain...")
http://ryan.mcgeary.org/2011/09/16/how-to-add-a-dnsimple-ssl-certificate-to-heroku/

As such, it would be great to:

1. update the heroku certs:add help text to clarify that:

• the reference to CRT can be either a .crt or .pem file, not just a .crt
• the CRT is actually "certificate concatenated with intermediate certificates"

2. Update the devcenter docs, so that they don't imply that heroku certs:add takes three arguments, for example by:

• changing "Add your certificate, any intermediate certificates bundles, and private key..." to "Add your certificate (including any intermediate certificates), and private key..."
• updating the example heroku certs:add code block to show the cat example.crt intermediates-bundle.crt > server.crt line too.

The current help text for reference:

$ heroku certs:add --help
Usage: heroku certs:add CRT KEY

add an SSL certificate to an app

 -a, --app APP       # app to run command against
 -r, --remote REMOTE # git remote of app to run command against
 --bypass            # bypass the trust chain completion step
 --domains DOMAINS   # domains to create after certificate upload
 --type TYPE         # type to create, either 'sni' or 'endpoint'

Example:

 $ heroku certs:add example.com.crt example.com.key

Many thanks!

[ransombriggs]

@edmorley This is a regression and I will start working on a fix

[ransombriggs]

@edmorley thanks for letting us know about this issue, I shipped a fix for add and update today which you can pull down with heroku update. I also updated the docs with a note about pem also being acceptable and an example for intermediate certificates.

@brettgoulder could you update the devcenter docs with an explanation of how to upload intermediate certificates?

Usage: heroku certs:add CRT KEY

add an SSL certificate to an app

 -a, --app APP       # app to run command against
 -r, --remote REMOTE # git remote of app to run command against
 --bypass            # bypass the trust chain completion step
 --domains DOMAINS   # domains to create after certificate upload
 --type TYPE         # type to create, either 'sni' or 'endpoint'

Note: certificates with PEM encoding are also valid

Example:

 $ heroku certs:add example.com.crt example.com.key

Certificate Intermediary Example:

 $ heroku certs:add intermediary.crt example.com.crt example.com.key

[edmorley]

Many thanks for the fix!

It looks like the only thing left is:

@brettgoulder could you update the devcenter docs with an explanation of how to upload intermediate certificates?

[mgan59]

Yup, just ended up here after I was about ready to write some profane messages to Heroku support... So more digging now, but essentially my SSL is a mess for my apps (wildcard ssl) because some are still using legacy ssl configurations and my latest environment I tried to use the GUI and it says my certificate isn't trusted because of intermediates.

So going forward should we just use CLI and don't look at the GUI? Because the GUI for my other apps says I don't have SSL configured even though everything looks fine when I run heroku certs:info -r production

All around the docs need updated because I'm still confused what I need to do exactly at this point.

[mgan59]

So for anyone that stumbled in here.... I ended up using the CLI to drive everything and needed to use the --type 'endpoint' flag to get my wildcards to work for multi-domains. Cert's set to SNI would be untrusted.

[edmorley]

It looks like the only thing left is:

@brettgoulder could you update the devcenter docs with an explanation of how to upload intermediate certificates?

:-)