Skip to content

Commit 5af306f

Browse files
accrawaccraw
authored
Merge pull request #102 from 1Password/accraw/add-dev-guide
add a guide for setting up ssh
2 parents 2690618 + 4cce04d commit 5af306f

File tree

2 files changed

+229
-0
lines changed

2 files changed

+229
-0
lines changed

‎dev-onboarding-guide/ssh-checker.sh

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
#!/bin/bash
2+
3+
echo "1Password SSH Setup Checker"
4+
echo "------------------------------------"
5+
6+
# Color definitions (optional)
7+
GREEN='\033[0;32m'
8+
RED='\033[0;31m'
9+
YELLOW='\033[1;33m'
10+
NC='\033[0m' # No Color
11+
12+
# Helper function: display check status
13+
print_status() {
14+
if [ "$2" = "OK" ]; then
15+
echo -e "[${GREEN}OK${NC}] $1"
16+
elif [ "$2" = "FAIL" ]; then
17+
echo -e "[${RED}FAIL${NC}] $1"
18+
elif [ "$2" = "WARN" ]; then
19+
echo -e "[${YELLOW}WARN${NC}] $1"
20+
else
21+
echo -e "[INFO] $1"
22+
fi
23+
}
24+
25+
# 1. Check SSH_AUTH_SOCK environment variable
26+
echo
27+
print_status "Checking SSH_AUTH_SOCK environment variable..."
28+
if [ -n "$SSH_AUTH_SOCK" ]; then
29+
print_status "SSH_AUTH_SOCK is set: $SSH_AUTH_SOCK" "OK"
30+
if [[ "$SSH_AUTH_SOCK" == *1Password* || "$SSH_AUTH_SOCK" == *1password* ]]; then
31+
print_status "SSH_AUTH_SOCK appears to point to a 1Password agent." "OK"
32+
else
33+
print_status "SSH_AUTH_SOCK may not point to a 1Password agent." "WARN"
34+
echo " Current value: $SSH_AUTH_SOCK"
35+
echo " Please ensure the SSH agent is enabled in 1Password desktop settings,"
36+
echo " restart your terminal, or check your shell configuration file (~/.zshrc, ~/.bash_profile, etc.)."
37+
fi
38+
else
39+
print_status "SSH_AUTH_SOCK is not set." "FAIL"
40+
echo " Please ensure the SSH agent is enabled in 1Password desktop settings,"
41+
echo " restart your terminal, or check your shell configuration file."
42+
fi
43+
44+
# 2. Check if keys are loaded in the SSH agent (ssh-add -L)
45+
echo
46+
print_status "Checking for keys loaded in the SSH agent (ssh-add -L)..."
47+
# ssh-add -L can return an error code if the agent isn't running, so capture output
48+
agent_keys_output=$(ssh-add -L 2>&1)
49+
agent_keys_exit_code=$?
50+
51+
if [ $agent_keys_exit_code -eq 0 ]; then
52+
if [[ "$agent_keys_output" == *"1Password"* || "$agent_keys_output" == *"1password"* || "$agent_keys_output" == *"//"* ]]; then # Common 1P key comment format
53+
print_status "1Password managed keys were listed from the SSH agent." "OK"
54+
echo " Listed keys:"
55+
echo -e " ${agent_keys_output}"
56+
elif [[ "$agent_keys_output" == "The agent has no identities." ]]; then
57+
print_status "No keys are loaded in the SSH agent." "WARN"
58+
echo " Ensure you have generated/imported SSH keys in 1Password and they are configured for use with the agent."
59+
echo " Alternatively, if your 1Password app is locked, try unlocking it."
60+
else
61+
print_status "Keys were listed from the SSH agent, but it's unclear if they are from 1Password." "WARN"
62+
echo " Listed keys:"
63+
echo -e " ${agent_keys_output}"
64+
echo " Please verify these are the keys you manage with 1Password."
65+
fi
66+
elif [ $agent_keys_exit_code -eq 2 ]; then # Error code for "Could not open a connection to your authentication agent."
67+
print_status "Could not connect to SSH agent. Is it running? (ssh-add -L returned error)" "FAIL"
68+
echo " Check your SSH_AUTH_SOCK setting and the status of the 1Password SSH agent."
69+
else # Other errors
70+
print_status "Error running ssh-add -L (Code: $agent_keys_exit_code)." "FAIL"
71+
echo " Error output: $agent_keys_output"
72+
fi
73+
74+
# 3. Test SSH connection to GitHub (optional)
75+
echo
76+
print_status "Testing SSH connection to GitHub (ssh -T [email protected])..."
77+
echo " This test will attempt to authenticate to GitHub."
78+
echo " Observe if 1Password prompts for biometrics or your system password."
79+
echo " A successful message often looks like 'Hi username! You've successfully authenticated...'"
80+
echo " (Do you want to run this test? [y/N])"
81+
read -r run_github_test
82+
83+
if [[ "$run_github_test" =~ ^[Yy]$ ]]; then
84+
echo " Running: ssh -T [email protected] ..."
85+
ssh -T [email protected]
86+
echo " Test complete. Check the output above and any 1Password prompts."
87+
else
88+
print_status "GitHub connection test was skipped."
89+
fi
90+
91+
echo
92+
echo "------------------------------------"
93+
echo "Check complete. If you encounter any issues, please refer to the onboarding guide"
94+
echo "or consult your team lead."

‎dev-onboarding-guide/ssh-guide.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Team SSH Key Onboarding Guide (Using 1Password)
2+
3+
## 1. Introduction
4+
5+
This guide offers a suggested standard process for using 1Password to manage your team's SSH keys securely and efficiently. By using 1Password for your SSH keys, you benefit from:
6+
7+
- **Enhanced Security:** Private keys are encrypted in your 1Password vault and only loaded into the SSH agent when needed, often protected by biometrics or Windows Hello.
8+
- **Improved Convenience:** No more repeatedly typing passphrases for SSH operations.
9+
- **Centralized Management:** Manage all your SSH keys alongside your other passwords and sensitive information in 1Password.
10+
- **Easy Setup & Consistency:** Establishes a consistent and secure SSH key management practice across the team.
11+
12+
## 2. Prerequisites
13+
14+
- **1Password Account:** A 1Password Business, Teams, or individual account (if team members manage their own).
15+
- **1Password Desktop Application:** Installed on macOS, Windows, or Linux.
16+
- [1Password Downloads Page](https://1password.com/downloads/)
17+
- **(Recommended) 1Password Browser Extension:** Installed.
18+
- **(Optional, for checker script & advanced use) 1Password CLI (`op`):** Installed.
19+
- [Install the 1Password CLI](https://developer.1password.com/docs/cli/get-started/)
20+
21+
## 3. Setup Instructions
22+
23+
### 3.1. Enable the 1Password SSH Agent
24+
25+
You need to enable the SSH agent in the 1Password desktop app.
26+
27+
1. **Open the 1Password desktop application.**
28+
2. **Navigate to Preferences/Settings:**
29+
- **macOS:** `1Password` menu > `Settings` (or `Preferences`) > `Developer` tab.
30+
- **Windows:** `⋮` (menu button) > `Settings` > `Developer` tab.
31+
- **Linux:** `Menu` > `Settings` (or `Ctrl+,`) > `Developer` tab.
32+
3. **Find the "SSH Agent" section.**
33+
4. **Check the box for "Use the SSH agent"** (or "Turn on SSH agent").
34+
5. **(Recommended)** Enable the option "Authorize SSH key use with biometrics or system password."
35+
6. **Set a default SSH key (optional):** If you have a key you use frequently, you can set it as the default.
36+
7. **Close the settings.** You might see on-screen instructions about how 1Password configures the SSH agent socket (`SSH_AUTH_SOCK`). Usually, restarting your terminal session will set this up automatically.
37+
38+
### 3.2. Generate or Import SSH Keys
39+
40+
#### Generate a New SSH Key in 1Password (Recommended)
41+
42+
1. In the 1Password desktop app, select the vault where you want to save the key.
43+
2. Click the "+ New Item" button and select "SSH Key."
44+
3. Choose "Generate a new private key."
45+
4. Select the key type (Ed25519 is recommended, or RSA) and bit length (4096 recommended for RSA).
46+
5. Give your key a clear title (e.g., `GitHub - [Your Name]`, `AWS Production - [Your Name]`).
47+
6. Click "Save." The public key will be visible within the item.
48+
49+
#### Import an Existing SSH Key into 1Password
50+
51+
If you must continue using an existing key, you can import it.
52+
53+
1. In the 1Password desktop app, click the "+ New Item" button and select "SSH Key."
54+
2. Choose "Import an existing key."
55+
3. Drag and drop your private key file (e.g., `id_rsa`) or select the file.
56+
4. Give your key a clear title.
57+
5. **Important:** After importing, **securely delete the original private key file** (e.g., `~/.ssh/id_rsa`) from your disk.
58+
59+
### 3.3. Add Your Public Key to Services
60+
61+
Once you've generated or imported an SSH key, you need to add its public key to the services you'll be connecting to (GitHub, GitLab, AWS, internal servers, etc.).
62+
63+
1. Open the SSH key item in 1Password.
64+
2. Click the "Copy" icon next to the public key field to copy the public key.
65+
3. Navigate to the SSH key settings page on each service and paste the copied public key.
66+
- **GitHub:** `Settings` > `SSH and GPG keys` > `New SSH key`
67+
- **GitLab:** `Preferences` > `SSH Keys`
68+
- For servers, add it to the `~/.ssh/authorized_keys` file on the server.
69+
70+
### 3.4. Verify SSH Client Configuration
71+
72+
Once the 1Password SSH agent is enabled, it should typically be used by your system's SSH client automatically. This happens because the `SSH_AUTH_SOCK` environment variable is set to point to the 1Password agent's socket file.
73+
74+
- **Restart Your Terminal Session:** After enabling the SSH agent or making changes to shell configuration files like `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`, restart your terminal session or open a new tab/window.
75+
- **Verification:** You can check if `SSH_AUTH_SOCK` points to a 1Password-related path by running the following in your terminal:
76+
77+
```bash
78+
echo $SSH_AUTH_SOCK
79+
```
80+
81+
The output should contain "1Password" (e.g., `/Users/youruser/Library/Group Containers/XXXXXXXXXX.com.1password/t/agent.sock`).
82+
83+
- **`~/.ssh/config` file (If Needed):**
84+
While usually not required, if you need specific configurations or have conflicts with other SSH agents, you can explicitly point to the 1Password agent in your `~/.ssh/config` file (adjust the path to your actual `SSH_AUTH_SOCK` value):
85+
86+
```bash
87+
Host *
88+
IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
89+
```
90+
91+
**Note:** The path for `IdentityAgent` can vary by OS and 1Password version. Check the 1Password app's settings for the correct path if you need to specify it manually.
92+
93+
## 4. Using Biometrics or System Password
94+
95+
With the 1Password SSH agent correctly set up, when you use an `ssh` command (e.g., `git pull`, `ssh user@server`), 1Password should prompt you for biometric authentication (fingerprint, face) or your system password. This allows secure and quick authentication instead of typing key passphrases.
96+
97+
## 5. Best Practices
98+
99+
- **Descriptive Key Names:** Name your SSH keys in 1Password clearly, indicating the service/machine and owner (e.g., `GitLab - MyProject - MacBookPro`, `AWS Staging Server Access`).
100+
- **Key Separation (Recommended):** If feasible, consider using different SSH keys for different critical services or environments.
101+
- **Regular Review:** Periodically review the public keys registered on your connected services (GitHub, etc.) and remove any that are no longer needed.
102+
- **Avoid Exporting Private Keys:** Only export private keys from 1Password if absolutely necessary and for a specific, secure purpose.
103+
104+
## 6. Troubleshooting
105+
106+
- **"Agent not running or not detected":**
107+
- Ensure the SSH agent is enabled in the 1Password desktop app settings.
108+
- Try restarting your terminal session.
109+
- Run `echo $SSH_AUTH_SOCK` to see if the expected path is displayed.
110+
- **"Still being prompted for the passphrase of an old key file":**
111+
- Check if old private key files (e.g., `~/.ssh/id_rsa`) still exist on your disk. If so, delete them securely.
112+
- Check your `~/.ssh/config` file for any settings that explicitly point to an old key (`IdentityFile ~/.ssh/id_rsa`).
113+
- **"Key not recognized by the server (Permission denied (publickey))":**
114+
- Verify that the correct public key has been added to the server's `~/.ssh/authorized_keys` file or the service's SSH key settings.
115+
- Confirm the 1Password SSH agent is serving the correct key (you can check with `ssh-add -L`; your 1Password key should be listed).
116+
- Check the SSH daemon logs on the server (e.g., `/var/log/auth.log` or `/var/log/secure`) for more detailed error messages.
117+
118+
---
119+
120+
### About the [SSH Setup Checker Script](ssh-checker.sh)
121+
122+
**What it does:**
123+
124+
This script is a small diagnostic tool designed to help you quickly verify if your local environment is correctly configured to use 1Password as your SSH agent. It performs several checks:
125+
126+
1. **`SSH_AUTH_SOCK` Variable:** Verifies that the `SSH_AUTH_SOCK` environment variable is set and appears to point to the 1Password agent.
127+
2. **Agent Accessibility & Key Listing:** Attempts to connect to the SSH agent (via `ssh-add -L`) to list loaded SSH keys, looking for indicators that they are managed by 1Password.
128+
3. **GitHub Connection Test (Optional):** Offers to run a test SSH connection to `[email protected]`. This doesn't check your GitHub permissions but allows you to observe if 1Password prompts for authentication (e.g., biometrics) as expected.
129+
130+
**Why you might want to use it:**
131+
132+
- **Troubleshooting:** If you're having trouble connecting to SSH servers after setting up 1Password for SSH, this script can help pinpoint common configuration issues.
133+
- **Verification:** After following the setup guide, run this script to confirm everything is working as expected.
134+
- **Self-Service Check:** Quickly perform a self-service diagnostic before reaching out for support.
135+
- **Peace of Mind:** Ensure your SSH operations are indeed being securely handled by 1Password.

0 commit comments

Comments
 (0)