Setting up multiple SSH profiles to manage multiple git accounts (MacOS)
Work, personal and freelance work all in one machine. Yes, that’s possible!
Quite a while ago, when I first ran into this problem of managing multiple git accounts, I had done a ton of research online. There were quite a lot of helpful articles, but they all had something missing. I had to patch together information from place to place to place. 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:
- Where are SSH keys stored on a Mac? What’s an RSA key?
- What is an SSH config and how can I set one up?
- What is a known_hosts file and what is an
- 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 in this article. I would say 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
.sshdirectory 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
📚 Soaking up some knowledge
Okay, let’s find it! Boot up your terminal, and head on over to
~/.ssh like so:
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?
To explain what these are, we need to talk about keys first:
- 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 email@example.com would use a private key from the file
my-awesome-key for authentication when opening a secure shell to
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 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.
Make sure you enter a simple passphrase (🔐) that you can keep safe elsewhere.
This will generate two files:
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.
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:
❗️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:
Here’s what your final config file will look like:
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
HostNameline 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.
Hostis a pattern matcher that is used to differentiate between these sets of configurations. Keep it the same as the
HostNameso it matches hosts in connections correctly without additional specification. If you want to use the
personal_keyas a fallback for every other URL, use an asterix
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.
Userfor most git based systems will just be
git. It will be different based on what you’re connecting to. E.g.
ec2-userif you’re connecting to an Amazon AWS EC2 instance at
IdentityFileasks for the location of the identity key we made. Type in the respective paths here.
UserKnownHostsFilespecifies an exact location to store all hosts you connect to when you’re using that profile. Provide the respective paths here.
IdentitiesOnlyspecifies 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.
Portspecifies what port number to use when connecting through SSH.
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.
ls -l to check the file permissions for everything in this folder:
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:
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
chmod 644 personal_key
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
644 sets (4+2) read and write for you, and (4) read permission for everyone else.
✅ Ready all the systems
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:
git pull, or
git pushto 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.
-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.
To list the keys you just added:
To delete all keys from just the agent, use:
⚠️ 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!
⚠️ NOTE: 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
Now paste it in the appropriate account, where SSH keys can be added. For github, you can get there through your personal settings:
Say you want to clone one of your repos locally. This is what the URL would look like:
firstname.lastname@example.org:some_cool_project is what you want to use when cloning this project with the command:
git clone email@example.com:some_cool_project.
Now, instead of
firstname.lastname@example.org, if you used a different
Host in the config file, you’d replace those parts of the clone command. For example, say you used
personal.github.com for the
Host you’d write:
git clone email@example.com: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!
Error: ssh-add: illegal option -- K - GitHub Help
The -K option is in Apple's standard version of ssh-add, which stores the passphrase in your keychain for you when you…
SSH Frequently Asked Questions
SSH: The Secure Shell (The Definitive Guide) Barrett, Silverman, & Byrnes / O’Reilly
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/