How to setup multiple SSH keys for multiple git accounts (MacOS + Windows)

When I first ran into this problem of managing multiple git accounts, I had done a ton of research online. There were a lot of helpful sources of information, but they all had something missing. I had to patch together information from a variety of places. I’m bringing all my learning together here, to pass the baton I was given.😅

Before we get started, let me outline a few of the questions I will be answering in this article. I’ll be addressing:

1. Where are SSH keys stored on a Mac? What’s an RSA key?
2. What is an SSH config and how can I set one up?
3. What is a known_hosts file and what is an id_rsa file?
4. How can I manage all my SSH keys? What are SSH keys anyway?

---

If you’re wondering what SSH is, we won’t be covering the answer to that here, but you are welcome to take a look at the official page from the organization behind SSH. This page is quite helpful and concise.

MacOS ships with the OpenSSH implementation of SSH. You’ll notice this particular statement from the site:

The OpenSSH client program is called ssh. The SSH client generally uses information in the .ssh directory in the user’s home directory. It also reads /etc/ssh/ssh_config, which contains its system-wide configuration.

For the purposes of this article, we won’t worry about the system-wide configuration in this article. In most Unix / Linux systems, the local configuration is found in the user’s home directory under .ssh.

📚 Soaking up some knowledge

Okay, let’s find it! Boot up your terminal, and head on over to ~/.ssh like so:

Make sure you’re in your root / home directory, then navigate to the .ssh folder

In this folder, you might see a couple of files, or none at all. For me, this is what it looks like below. What is this nonsense?

Usually, you might find a known_hosts file here already. You might also have an id_rsa and an `id_rsa.pub file here.

To explain what these are, we need to talk about keys first. There are a few types:

• Authorized keys and Identity keys are user keys. Authorized keys are public keys, similar to a lock. (🔒) Identity keys, are private keys, similar to a key that opens that lock. (🔑)
• Host keys are for host authentication, i.e. the entity you are trying to connect to. They are public keys. (🔒)
• The known_hosts file is where OpenSSH stores or remembers hosts that it has connected to previously. It only remembers host keys.
• Session keys encrypt the data in a connection. They change every session and use the host key to generate or use a mutual shared key.

We’ll get into how the key exchange works in a later article.

We’re primarily concerned with Identity keys and Host keys. Your identity keys when generated with no options look like id_<algorithm it was made with> by default and are usually in this .ssh folder. RSA is the most common algorithm in use, and the most widely supported, so you’ll see keys that look like id_rsa. RSA also happens to be the default algorithm. (Click here if you want to know more about the other algorithms)

However, it is possible to specify any file name, and any location when creating a private key. You can also provide a custom path pointing to a key somewhere else, with the -i option to the SSH client. For example, ssh -i /home/me/somepath/my-awesome-key [e-mail] would use a private key from the file my-awesome-key for authentication when opening a secure shell to awshost.amazon.com as ec2-user.

💻 Setup

It’s time to generate a key! To do this, we’ll need to use the ssh-keygen command to make a key with a certain algorithm. Here’s what we’re going to run:

ssh-keygen -t rsa -f personal_key -b 2048

-t specifies the algorithm that makes the key. -f specifies a custom name for the key, and an alternate location if it’s in the form of a path. -b specifies how many bits long the key will be. By default, ssh-keygen will use the RSA algorithm with 2048 bit length. So, all we really need to do is specify a custom name!

⚠️ Make sure an existing id_rsa and id_rsa keypair don’t exist already. If they do, keygen will ask if you want to overwrite. This will permanently delete that old key you might have used elsewhere! Back it up, make a key with a different name, or if you’re sure, overwrite it.

Run the command in the same folder you are in to generate a key in that location. A passphrase is a good idea!

Make sure you enter a simple passphrase (🔐) that you can keep safe elsewhere.

If successful, you’ll see something like this.

This will generate two files: personal_key and personal_key.pub. The first is your private key (🔑), the second is your public key (🔒).

Now, repeat the same process for your work account. In this manner, you can make as many keys as you want. But for this article, let’s make one more.

A new work_key with a different passphrase.

It’s time to make two hosts files for each of your profiles. You don’t have to make two, but it’s nice to keep the profiles completely separate. Run the following commands to generate the two files:

touch known_hosts
touch known_hosts_work

❗️NOTE: if you have a known_hosts file here already, there’s no need to make another one. If you want to rename it, you can do that — just make sure you use that name for the following steps.

🛠 Connect the dots with a config file

Finally, let’s bring it all together in a config file. There’s two of them, one for local, and one for global. As mentioned before, we’re focussing on the local. Use the following command to make a config file:

touch config

Here’s what your final config file will look like:

Your key names here might be different based on what you used.

The config file is organized by hosts. Each host definition has a set of connection options:

• Comments can be made with # at the start of a line. These are for your eyes.
• The URL on the HostName line is the exact base URL at which your repository resides. This is your destination. For example, if you have a personal account on github, with personal projects, the URL will be github.com. In my case, I have my work version-control host URL, and my personal account at github.com.
• Host is a pattern matcher that is used to differentiate between these sets of configurations. Keep it the same as the HostName so it matches hosts in connections correctly without additional specification. If you want to use the personal_key as a fallback for every other URL, use an asterix * as the Host. The Host * configuration set is usually at the bottom of the config file, so it tests very configuration set until it gets to this one, if none of the previous Host patterns match.
• User for most git based systems will just be git. It will be different based on what you’re connecting to. E.g. ec2-user if you’re connecting to an Amazon AWS EC2 instance at ec2-user@some_server.amazonaws.com.
• IdentityFile asks for the location of the identity key we made. Type in the respective paths here.
• UserKnownHostsFile specifies an exact location to store all hosts you connect to when you’re using that profile. Provide the respective paths here.
• IdentitiesOnly specifies that only these keys provided must be used to connect to a host, even if another service, like the ssh-agent, offers a key for use.
• Port specifies what port number to use when connecting through SSH.

♻️ Cleanup

Let’s do some cleanup before we move on to the final step. We need to make the keys only readable by you, that way no one else can modify or tamper with your private keys.

Run ls -l to check the file permissions for everything in this folder:

Running `ls -l` will show you the permissions on each file you’ve made

You want every file in here to be readable / writable by you, and only readable by everyone else — which means each file will have this: -rw-r--r-- on the far left column. Let me illustrate how permissions work:

There’s 2 ways to set permissions: with letters or with numbers

As you can see in the picture above, there's 2 ways to set permissions. Either one of the following commands in your terminal work.

chmod go-wx, u=rw personal_key

or

chmod 644 personal_key

With letters

go-wx removes write and execute permissions from the group and others. u=rw sets the user (you) to only have read and write permissions.
+ adds permissions that follow. — removes permissions that follow. = sets the permissions to exactly what follows.

You can separate as many sets of these as you want, with commas ,.

With numbers

644 sets (4+2) read and write for you, and (4) read permission for everyone else. This should be done on the public keys only.
600 sets (4+2) read and write permissions for you, and no permissions for everyone else. This should be done on all the secret keys.

Either method you use, make sure all the public keys show rw for you and r for everyone else, while the secret keys show rw for you and nothing for everyone else.

✅ Ready all the systems

Almost there!

The last step is to add the keys to an ssh-agent so you don’t have to enter the passphrase and specify the key to use every time you ssh to a host. The agent essentially acts like your personal assistant; a butler of sorts. Take this quote from github.com:

When you git clone, git fetch, git pull, or git push to a remote repository using SSH URLs, you'll be prompted for a password and must provide your SSH key passphrase.

Why type the passphrase everytime, when the ssh-agent can do it for you?

Let’s add both our keys to the agent using the following command:

ssh-add -K personal_key
ssh-add -K work_key

✋you might be asked for your passphrase when adding your keys.
✋the -K option might not work for you. This is a Mac only command that adds the key passphrase to your OS keychain. If you forget your passphrase, you can access it through Keychain Access. If you have trouble using this option, check the troubleshooting section at the end of this article.

Macs have a -K and -A option which can be used to manage your passphrases through the OS’ Keychain.

With the latest macOS (Sierra or above), there are 2 new configuration options which are very useful.

To list the keys you just added:

ssh-add -l

To delete all keys from just the agent, use:

ssh-add -D

⚠️ Note that your keys are on an agent, so a passphrase isn’t required. Make sure no one else has access to your computer!

🔗 Test your connection

Now it’s time to add your keys to your accounts. Use the following to copy your respective key:

pbcopy < personal_key.pub
cat personal_key.pub | pbcopy # alternative command!

⚠️ Notice how the .pub key is used. This is the public (🔒) identity key that you want to provide to your git service. Don’t use your private (🔑) key! (the other file without the .pub extension)

Now paste it in the appropriate account, where SSH keys can be added. For github, you can get there through your personal settings:

For Github, this is where you’d add your shiny new key. NOTE: paste it exactly as it appears in the key file!

Say you want to clone your repo locally. This is what the URL would look like:

Github says [e-mail]:some_cool_project is what you want to use when cloning this project with the command: git clone [e-mail]:some_cool_project.
Now, instead of [e-mail], if you used a different User and Host in the config file, you'd replace those parts of the clone command. For example, say you used another_user for User and personal.github.com for the Host you'd write:

git clone [e-mail]:some_cool_project

⚠️ Your git user name and email must be configured locally for every project, or you'll end up making commits on work and personal accounts with the global user name and email you've set for git!

💡 I'll do a deep-dive into the git config in a later article. Stay tuned!

---

You're all done! No need to manually specify the key you want to use, every-time you connect with SSH. The config and agent will automatically determine what key to use based on the host you're connecting to.

I hope that this article helped you today. If you feel like it'll help others, or if you have a correction or suggestion, I would love to hear from you. If you want to replicate this article for other operating systems, I would love to hear from you as well. Cheers!

---

Troubleshooting links

https://medium.com/r/?url=https%3A%2F%2Fhelp.github.com%2Fen%2Farticles%2Ferror-ssh-add-illegal-option----k

Further exploration

https://medium.com/r/?url=http%3A%2F%2Fwww.snailbook.com%2Ffaq%2Fabout-agent.auto.html
Understand ssh-agent and ssh-add - http://blog.joncairns.com/2013/12/understanding-ssh-agent-and-ssh-add/
SSH Key types (read about the better ed25519 key algorithm that is now in use)- https://chealion.ca/2016/06/20/ssh-key-types-and-cryptography-the-short-notes/

Comments

[Claire Lu]

Thank you so much.

[Folakemi]

This was super helpful! Thanks!!

[Sagar Baver]

Thanks for putting this together in a nice and easy-to-follow tutorial.

The ssh agent may complain if you attempt to add a key whose file permissions are overly permissive. For instance, a 644 permission combination on a personal key returned the following error.
See dev-to-uploads.s3.amazonaws.com/up...

However, setting the permissions to 600 did the trick for me.

[Brian]

I don't think we need cd $HOME before cd ~/.ssh?

[Yash Kadaru]

Yep you're right it's not needed! Just thought I'd put that in the screenshot to show newbies how to get to their home directory if they found themselves somewhere else

[Anton Shapoval]

Thank you very much for your useful work!