Managing SSH Keys
Last updated May 11, 2022
Table of Contents
Configure SSH keys to enable tunneling (
heroku ps:exec) for Private Spaces apps.
SSH keys attached to a user account are only relevant for tunneling into apps with
ps:exec within Private Spaces.
Heroku supports RSA and DSA key formats. ECDSA keys are currently not supported.
Git Bashapplication. A shortcut for this application is typically placed on the Desktop, installed as part of the Heroku CLI.
Generate an SSH Key
Generate a public-private key pair using
$ ssh-keygen -t rsa Generating public/private rsa key pair. Enter file in which to save the key (/Users/adam/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /Users/adam/.ssh/id_rsa. Your public key has been saved in /Users/adam/.ssh/id_rsa.pub. The key fingerprint is: a6:88:0a:0b:74:90:c6:e9:d5:49:d6:e3:04:d5:6c:3e email@example.com
Press enter at the first prompt to use the default file location. Next, type a secure passphrase for the key.
Add Keys to a Heroku Account
keys:add CLI command to upload one or more keys and associate them with your account. The Heroku CLI searches for keys in the default location and ask to upload them:
$ heroku keys:add Found an SSH public key at /Users/adam/.ssh/id_rsa.pub ? Would you like to upload it to Heroku? [Y/n] Uploading /Users/adam/.ssh/id_rsa.pub SSH key... done
--yes flag to
keys:add to bypass the confirmation:
$ heroku keys:add --yes Found an SSH public key at /Users/adam/.ssh/id_rsa.pub Uploading /Users/adam/.ssh/id_rsa.pub SSH key... done
If the key is in an alternate location, specify the location when running the command. Declaring the path of the key also bypasses the confirmation (
--yes isn’t required).
$ heroku keys:add ~/.ssh/id_rsa.pub Uploading /Users/adam/.ssh/id_rsa.pub SSH key... done
Always confirm the
.pub file extension. The
.pub file is the public half of the private-public SSH key pair. The private half doesn’t have a file extension. Never upload the private half to Heroku or share it with anyone.
Heroku sends an email notification to the user’s email address after uploading a new key for security purposes.
Remove Keys From a Heroku Account
Keys that must be revoked and disassociated with a Heroku account are removable via the Heroku CLI and Heroku Dashboard.
Revoke a key using the Heroku CLI using
$ heroku keys:remove firstname.lastname@example.org Removing email@example.com SSH key... done
If the key doesn’t have a name or doesn’t have a unique name, specify a portion of the public key string when removing the key via the CLI. For example:
$ heroku keys:remove AAAAAAAAAA Removing firstname.lastname@example.org SSH key... done
Remove all keys on a user account with
$ heroku keys:clear Removing all SSH keys... done
Revoke a key using the Heroku Dashboard on the Account Settings page, under the SSH Keys section. Click the X to delete a key.
View Associated Keys
View a list of all of the keys associated with your account using the
$ heroku keys === email@example.com Keys ssh-rsa AAAABDD3cC...2kPRNJqfKp firstname.lastname@example.org
keys to see the entire output of the key string. If the user account has multiple keys, consider redirecting the command’s output to text (
heroku keys --long > keys.txt) or piping the output to
heroku keys --long | less) for added readability.
Validate Key Functionality
Confirm assigned SSH key(s) work by starting a one-off dyno for an app within a Shield Private Space:
$ heroku run bash -a shield-space-app-name
A successful connection indicates the key(s) are correct and functioning properly.
Common SSH Key Problems
Configured Key Mismatch
A common source of authentication failure when using an SSH key provided to Heroku is that the uploaded key doesn’t match the key provided during the authentication process. If, during testing,
Permission denied (publickey) is displayed, validate the key’s functionality and confirm which key
ssh is using.
ssh -v prints the absolute path for the key with this message:
debug1: Offering public key: /path/to/key_file ...
If the key doesn’t match, either upload the correct key to Heroku or configure
ssh to use a different key for the
heroku.com host. Place the following in
Host heroku.com HostName heroku.com IdentityFile /path/to/key_file IdentitiesOnly yes
/path/to/key_file with the absolute path to the appropriate key without the
Key Already in Use
This key is already in use by another account appears when attempting to upload an SSH key, the key is associated with another Heroku user. Confirm Heroku has the correct key, log into the other account and remove the SSH key, or generate a new key and upload it.