Cheat Sheets › 1Password for SSH

1Password for SSH on a Mac

Step by step: keep your SSH keys in 1Password and have Terminal's ssh use them, with a Touch ID check, one server at a time. Background on keys and the config file is on the SSH sheet.

READ-ONLY only looks; safe CHANGES THINGS be careful ON YOUR MAC in Terminal or the 1Password app $ = you type this

Set up once

#1How it works

Your private keys live inside 1Password, not as files on your Mac. When you log in to a server, ssh asks 1Password for the right key, and 1Password checks with you first.

1. You type ssh ubuntu1 2. Config entry which address, user, and which key 3. 1Password finds the matching private key 4. You approve Touch ID or your 1Password password 5. Server you're in
The pieces you'll set up
1Password's SSH agentA setting in 1Password that lets ssh ask it for keys. Turned on once (step 3).
SSH Key itemsEach private key, stored in 1Password (step 4).
.pub filesThe public half of each key, saved in ~/.ssh. Safe to keep on your Mac; it tells ssh which key to ask for (step 5).
One config entry per serverIn ~/.ssh/config, pointing that server at 1Password and at its key (step 6).
WHY THIS WAYEach server says exactly which key it uses, so the right key is always offered, and servers you haven't switched over keep working exactly as before. You can move one server at a time.
↑ Back to top

#2Before you start

CHANGES THINGSON YOUR MAC
You need
  • The 1Password app for Mac (version 8), installed, signed in, and unlocked.
  • Your existing key files (for example AWS .pem files), and a server you can currently log in to, to test with.
Make sure the ~/.ssh folder and config file exist
mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/config && chmod 600 ~/.ssh/config

Safe to run even if they already exist: mkdir -p and touch don't change existing ones; chmod sets "only you" permissions, which ssh requires. No output = done.

Back up your config file
cp ~/.ssh/config ~/.ssh/config.backup

Your safety net. To undo every change later: cp ~/.ssh/config.backup ~/.ssh/config.

↑ Back to top

#3Turn on 1Password's SSH agent

CHANGES THINGSON YOUR MAC

Done once per Mac, in the 1Password app.

  1. Open 1Password and unlock it.
  2. From the menu bar: 1Password › Settings (or press Cmd+,).
  3. Click Developer.
  4. Turn on Use the SSH Agent.
  5. If offered, also turn on Display key names when authorizing connections. The approval prompt then names the key, so you can see the right one is being used.
Check the agent is running (read-only)
ls -l ~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock
  • A line starting with srw = the agent is on. (s means it's a "socket," a connection point programs talk through.)
  • No such file or directory = the setting isn't on yet, or 1Password isn't running.
THE AGENT'S ADDRESSThat long path is where ssh finds 1Password. You'll paste it into each config entry in step 6. It's the same on every Mac.
↑ Back to top

For each key

#4Add a key to 1Password

CHANGES THINGSON YOUR MAC
⚠ PUT IT IN THE RIGHT VAULTBy default, the SSH agent only uses keys in your Personal vault (called Private on some accounts). A key saved in any other vault is ignored, and the error you get doesn't say so (see step 9).
Choose a name

Name each key for what it's for, so it's easy to identify: a client, a group of servers, or a purpose. Use the same name for the 1Password item and, in step 5, the .pub file. On this sheet the name is shown as key-name.

Option A: import a key you already have (like an AWS .pem)
  1. Make sure the Personal/Private vault is selected in the sidebar.
  2. Click + New Item and choose SSH Key.
  3. Click Add Private Key › Import a Key File, and pick the key file (for example key-name.pem).
  4. If the key file has its own passphrase, 1Password asks for it once.
  5. Set the item's title to key-name and click Save.
Option B: create a new key in 1Password
  1. In the Personal/Private vault, click + New Item and choose SSH Key.
  2. Click Add Private Key › Generate a New Key, choose Ed25519, and click Generate.
  3. Set the title to key-name and click Save.

The private key never leaves 1Password. You'll still need to put its public half on each server (SSH sheet, section 5).

What you'll see in the item
private keyHidden. Never needs copying out.
public keyOne long line starting with ssh-rsa or ssh-ed25519. You'll use it in step 5.
fingerprintA short ID starting with SHA256:. Used to check that files and items match.
key typeEd25519, or RSA for most AWS .pem files. Both work.
↑ Back to top

#5Save the key's public half in ~/.ssh

CHANGES THINGSON YOUR MAC

Each config entry points at a .pub file, so ssh knows which key to ask 1Password for. A .pub file is only the lock, not the key, so it's safe to keep on your Mac.

Check first: does it already exist? (read-only)
ls ~/.ssh/*.pub

If key-name.pub is already listed, skip to the fingerprint check below.

Way 1: copy it from 1Password (works for any key)
  1. Open the SSH Key item in 1Password and copy the public key field (hover over it and click Copy).
  2. In Terminal, save the clipboard as the file:
pbpaste > ~/.ssh/key-name.pub

pbpaste prints what's on your clipboard; > saves it into a new file. Use your key's name. No output = done.

Way 2: make it from the private key file (if you still have the file)
ssh-keygen -y -f /path/to/key-name.pem > ~/.ssh/key-name.pub

Reads the private key file and saves only its public half. Use the real path to your key file.

Check it matches 1Password (read-only)
ssh-keygen -lf ~/.ssh/key-name.pub 256 SHA256:k3Xr9Qe2w… key-name (ED25519)

Compare the part after SHA256: with the fingerprint in the 1Password item. The first 6 to 8 characters matching is enough. No match = different key: don't use that file.

⚠ CAREFULPaste only the public key into the .pub file. And with >, if that file name already exists, it's replaced, which is why the check above comes first.
↑ Back to top

For each server

#6Add the config entry

CHANGES THINGSON YOUR MAC

Each server gets its own entry, and each entry points at 1Password itself. There's no catch-all Host * line, so servers you haven't switched yet are left exactly as they are.

Open the config file
nano ~/.ssh/config
An existing server: before and after

Before (key file on disk)

Host ubuntu1
  HostName 203.0.113.10
  User ubuntu
  IdentityFile ~/keys/key-name.pem

After (key from 1Password)

Host ubuntu1
  HostName 203.0.113.10
  User ubuntu
  IdentityFile ~/.ssh/key-name.pub
  IdentitiesOnly yes
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

Leave Host, HostName, and User as they were. Change the IdentityFile line and add the last two.

The three lines that make it use 1Password
IdentityFile ~/.ssh/key-name.pubWhich key: the public file from step 5. ssh asks 1Password for the private key that matches it.
IdentitiesOnly yesOffer only that key. Without it, ssh may try every key in 1Password, and the server hangs up after about 6 wrong ones.
IdentityAgent "…agent.sock"Where to ask: 1Password's agent, from step 3. Copy it exactly, including the quotes; the space in "Group Containers" breaks it otherwise.
A new server: copy this whole entry
Host NICKNAME HostName ADDRESS User ubuntu IdentityFile ~/.ssh/key-name.pub IdentitiesOnly yes IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

Paste it at the end of the file, then replace NICKNAME, ADDRESS, and key-name. User is ubuntu on Ubuntu, ec2-user on Amazon Linux. Leave a blank line between entries.

Save and exit

Save: Ctrl+O, then Enter. Exit: Ctrl+X.

ONE KEY, MANY SERVERSSeveral entries can point at the same .pub file. Only the Host and HostName lines differ.
↑ Back to top

#7Test and confirm

READ-ONLYON YOUR MAC
1. Check the entry reads the way you meant
ssh -G ubuntu1 | grep -i identit identitiesonly yes identityagent /Users/me/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock identityfile ~/.ssh/key-name.pub

Shows the settings ssh will use for ubuntu1, without connecting. All three lines should match your entry. (Replace ubuntu1 with your nickname.)

2. Check 1Password is offering keys
SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ssh-add -l 256 SHA256:k3Xr9Qe2w… key-name (ED25519)
  • One line per key 1Password will hand out, with its fingerprint and name. Your key should be listed.
  • The agent has no identities = the agent is on, but sees no keys. Check the vault (step 4).
3. Log in
ssh ubuntu1
  • A 1Password window asks to allow Terminal to use the key, naming it. Approve with Touch ID or your 1Password password.
  • Then you're logged in as usual. Type exit to log out.
  • 1Password remembers your approval for a while, so you won't be asked on every login.
⚠ NEW KEY? PUT IT ON THE SERVER FIRSTA key imported from an existing .pem already works on that server. A key you just created doesn't yet: add its public half to the server's authorized_keys first (SSH sheet, section 5), and keep your old login open while you test.
↑ Back to top

#8Switch the rest over, then clean up

CHANGES THINGSON YOUR MAC
For each remaining server
  1. Is its key in 1Password, in the Personal/Private vault? If not: step 4.
  2. Is its .pub file in ~/.ssh, with a matching fingerprint? If not: step 5.
  3. Change its config entry: step 6.
  4. Test it: step 7.

One server at a time. The config backup from step 2 only needs making once.

When every server works through 1Password

The old private key files (like .pem files) aren't needed anymore, since 1Password holds the keys. Don't delete them right away:

  1. Confirm each key is in 1Password (step 7, check 2 lists them).
  2. Move the old key files into one folder, for example ~/old-keys, so nothing uses them.
  3. Use your servers normally for a couple of weeks.
  4. If nothing needed them, delete that folder.
⚠ KEYS ON THE DESKTOP OR IN DOCUMENTSIf iCloud's "Desktop & Documents" syncing is on, private key files there are being copied to iCloud too. Once they're safely in 1Password, move them out of those folders.
Optional: use a vault other than Personal/Private

To keep server keys in their own vault, 1Password needs a small settings file listing the vaults the agent may use. Create it:

mkdir -p ~/.config/1Password/ssh
nano ~/.config/1Password/ssh/agent.toml
⚠ Example only: use your own vault names, spelled exactly as in 1Password
[[ssh-keys]] vault = "Private" [[ssh-keys]] vault = "Server Keys"

Each [[ssh-keys]] block allows one vault. Once this file exists, only the vaults listed are used, so keep your Personal/Private vault in the list if it still holds keys.

↑ Back to top

When it doesn't work

#9Troubleshooting

READ-ONLYON YOUR MAC
WARNING: UNPROTECTED PRIVATE KEY FILE! naming a .pub file, then Permission deniedMisleading. 1Password didn't hand over the key, so ssh tried the .pub as a private key. Almost always the key is in the wrong vault (step 4). Also check the agent is on (step 3) and the IdentityAgent line (step 6). Don't change the file's permissions.
Permission denied (publickey) with no warning1Password offered the key, but the server doesn't accept it. Check the User line (ubuntu vs ec2-user), the fingerprint (step 5), and that the key is on the server (step 7's red box).
No 1Password window appearsIt may be behind other windows; check the Dock. Or 1Password is locked or not running. Unlock it and try again.
Too many authentication failuresThe entry is missing IdentitiesOnly yes (step 6).
The agent has no identitiesAgent on, but no keys visible: wrong vault, or a vault left out of agent.toml (step 8).
Could not open a connection to your authentication agent / No such fileThe agent isn't on. Turn on Use the SSH Agent (step 3) and make sure 1Password is running.
Bad configuration option / line 12: …A typo in ~/.ssh/config at that line number. Open it with nano and compare with step 6.
Connection timed outNot a 1Password problem: ssh can't reach the server. See SSH sheet, Troubleshooting.
See exactly what ssh is doing
ssh -v ubuntu1

Look for Offering public key:, which names the key it's trying, and Authenticated to for success. Ctrl+C stops it.

UNDO EVERYTHINGPut the config back the way it was: cp ~/.ssh/config.backup ~/.ssh/config. Your original key files still work as before, as long as you haven't deleted them (step 8).
↑ Back to top