How to setup multiple SSH keys for multiple git accounts (MacOS + Windows)
Tags: git, workflow, ssh, beginners
Published: 2019-04-25 00:02:24

---
title: How to setup multiple SSH keys for multiple git accounts (MacOS + Windows)
published: true
description: Work, personal and freelance work all in one machine. Yes, that's possible!
tags: git, workflow, ssh, beginners
cover_image: https://cdn-images-1.medium.com/max/2600/1*7AqcP8ifu7qwCf2QSSHpZQ.png
series: development workflow
---

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](https://www.ssh.com/ssh/) 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:
![.ssh directory under your home directory](https://thepracticaldev.s3.amazonaws.com/i/3yw6m5dc2r8c4wc17yq0.jpg)
<figcaption>Make sure you’re in your root / home directory, then navigate to the .ssh folder</figcaption>

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?
![.ssh folder might have multiple files in it already](https://thepracticaldev.s3.amazonaws.com/i/vy4k86df3q5k6sxiak7x.jpg)
<figcaption>Usually, you might find a known_hosts file here already. You might also have an id_rsa and an `id_rsa.pub file here.</figcaption>

To explain what these are, we need to talk about [keys](https://www.ssh.com/ssh/key/) 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](https://security.stackexchange.com/questions/84773/difference-between-public-key-and-host-key-and-security-of-host-key?newreg=4846631c015449f5bc46f97c27e7a48e) 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](https://security.stackexchange.com/questions/23383/ssh-key-type-rsa-dsa-ecdsa-are-there-easy-answers-for-which-to-choose-when))

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 ec2-user@awshost.amazon.com` 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.

![using ssh-keygen to make a key](https://thepracticaldev.s3.amazonaws.com/i/rcq6vrvmudmthz4cnhm6.jpg)
<figcaption>Run the command in the same folder you are in to generate a key in that location. A passphrase is a good idea!</figcaption>

Make sure you enter a simple passphrase (🔐) that you can keep safe elsewhere.
![successful key-gen](https://thepracticaldev.s3.amazonaws.com/i/0q058r1mywf171ragai3.jpg)
<figcaption>If successful, you’ll see something like this.</figcaption>

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.
![another work key made with ssh-keygen](https://thepracticaldev.s3.amazonaws.com/i/319a3lj4116j4la4xupm.jpg)
<figcaption>A new work_key with a different passphrase.</figcaption>

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](https://www.ssh.com/ssh/config/). 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:
![the final config file showing 2 profiles](https://thepracticaldev.s3.amazonaws.com/i/y2s1d99u8bs5bih8v1rv.jpg)
<figcaption>Your key names here might be different based on what you used.</figcaption>

The config file is organized by hosts. Each host definition has a set of [connection options](https://linux.die.net/man/5/ssh_config):
+ 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 in bash](https://thepracticaldev.s3.amazonaws.com/i/h9iu416p6jqr45unu354.jpg)
<figcaption>Running `ls -l` will show you the permissions on each file you’ve made</figcaption>

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:
![Permissions on a linux based system can be set one of two ways: with letters or with numbers](https://thepracticaldev.s3.amazonaws.com/i/sriplvgxhk396hynw3ck.png)
<figcaption>There’s 2 ways to set permissions: with letters or with numbers</figcaption>

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](https://help.github.com/en/articles/which-remote-url-should-i-use):
> 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](https://help.github.com/en/articles/working-with-ssh-key-passphrases/).

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](https://apple.stackexchange.com/questions/265131/recover-ssh-private-key-passphrase-from-keychain). If you have trouble using this option, check the *troubleshooting* section at the end of this article.
![ssh-add help page](https://thepracticaldev.s3.amazonaws.com/i/ncbkm6n8cl05ksxc3sj0.jpg)
<figcaption>Macs have a -K and -A option which can be used to manage your passphrases through the OS’ Keychain.</figcaption>

![Additional config file options for MacOS related to Keychain](https://thepracticaldev.s3.amazonaws.com/i/84s1li7by2mpovcwcsbt.jpg)
<figcaption>With the latest macOS (Sierra or above), there are 2 new configuration options which are very useful.</figcaption>

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:

![Adding SSH keys on Github](https://thepracticaldev.s3.amazonaws.com/i/mu4p4kvsq4yll3zhx22h.jpg)
<figcaption>For Github, this is where you’d add your shiny new key. NOTE: paste it exactly as it appears in the key file!</figcaption>

Say you want to clone your repo locally. This is what the URL would look like:
![Github repo SSH url](https://thepracticaldev.s3.amazonaws.com/i/gyu39iu7wujetez6tdvi.jpg)

Github says `git@github.com:some_cool_project` is what you want to use when cloning this project with the command: `git clone git@github.com:some_cool_project`.
Now, instead of `git@github.com`, 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 another_user@personal.github.com:some_cool_project

⚠️ Your git user name and email must be [configured locally for every project](https://medium.com/r/?url=https%3A%2F%2Fhelp.github.com%2Fen%2Farticles%2Fsetting-your-commit-email-address-in-git), 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/