Bitwarden SSH Agent 使用指南
Bitwarden SSH Agent 是 Bitwarden 密码管理器桌面应用提供的一项功能。它可以让 Bitwarden 充当 SSH Agent，安全地加密和存储你的 SSH 密钥，用于以下场景：
- 认证远程服务器
- 为 Git 提交签名
- 与其他基于 SSH 的服务交互
Bitwarden SSH Agent 将你的所有 SSH 密钥集中在一个安全的位置进行组织和保护。你可以通过桌面应用、网页应用、浏览器扩展和移动应用访问这些密钥。SSH 密钥可以在桌面应用、网页应用和浏览器扩展中生成。
注意：SSH Agent 需要 Bitwarden 版本 2025.1.2 或更高。
存储 SSH 密钥
你可以在 Bitwarden 桌面应用中创建新的 SSH 密钥并保存。Bitwarden 中的 SSH 密钥会存储以下信息：
| 字段 | 描述 |
|---|
| 密钥名称 | SSH 密钥的名称 |
| 私钥 | 用于服务器安全连接的敏感数据。私钥应妥善保管，Bitwarden 可帮助生成安全唯一的私钥。 |
| 公钥 | 需要共享给目标服务器的部分密钥 |
| 指纹 | 由公钥生成的短唯一字符串，用于标识（如验证 SSH 签名的 Git 提交） |
存储在 Bitwarden 中的 SSH 密钥可使用密码管理器的各项功能，例如文件夹、收藏夹、主密码重新提示、笔记、克隆项目、附件和自定义字段。
创建新的 SSH 密钥
你可以使用 Bitwarden 桌面应用、网页应用或浏览器扩展 创建新的 SSH 密钥。创建完成后，可在桌面应用、网页应用、浏览器扩展和移动应用中访问。
- 点击 New（新建） 按钮，选择 SSH key（SSH 密钥） 作为项目类型。
注意：目前 Bitwarden 仅支持生成 ED25519 类型的 SSH 密钥。
- 填写名称等信息，完成后点击保存图标。
以下是缺失的「Organization SSH keys（组织 SSH 密钥）」部分的完整中文翻译：
组织 SSH 密钥
SSH 密钥可以创建并存储在组织集合中。组织成员只要拥有相应权限，就可以创建、管理和访问组织拥有的 SSH 密钥。关于集合权限的更多信息，请参阅集合权限说明。
将新的共享 SSH 密钥添加到组织保险库
- 在桌面应用或网页应用的保险库视图中，点击 New（新建） 按钮，选择 SSH key（SSH 密钥）。
提示：组织所有者、管理员以及部分自定义角色的用户也可以直接从 Admin Console（管理控制台） 执行此操作，从而跳过部分步骤。
- 在 Owner（所有者） 下拉菜单中，选择你要归属的组织。
- 在 Collections（集合） 下拉菜单中，选择要与之共享此密钥的一个或多个集合。
分享 SSH 密钥示意图
注意：
一般来说，使用 SSH 密钥的资源都支持为每个用户单独配置密钥。我们强烈建议在将 SSH 密钥分享到组织之前，先仔细阅读 SSH 密钥的最佳实践。
编辑现有密钥（Edit existing keys）
一旦 SSH 密钥保存到你的 Bitwarden 保险库，你就可以编辑密钥的名称、所有者、文件夹和自定义字段等信息。
Desktop（桌面应用）
- 打开 Bitwarden 桌面应用，进入 SSH keys 视图。
- 找到你要编辑的 SSH 密钥，然后点击 编辑（铅笔图标）。
- 完成所需修改后，点击 保存。
Web app（网页应用）
- 打开 Bitwarden 网页应用，进入 SSH keys 视图。
- 找到并选择你要编辑的 SSH 密钥。屏幕上会弹出对话框，然后点击 Edit（编辑）。
- 完成所需修改后，点击 Save（保存）。
Mobile（移动应用）
- 打开 Bitwarden 移动应用，进入 SSH keys 视图。
- 找到你要编辑的 SSH 密钥，然后点击 Edit（编辑）。
- 完成所需修改后，点击 Save（保存）。
Browser extension（浏览器扩展）
- 打开 Bitwarden 浏览器扩展，进入 SSH keys 视图。
- 找到并选择你要编辑的 SSH 密钥。屏幕上会弹出对话框，然后点击 Edit（编辑）。
- 完成所需修改后，点击 Save（保存）。
将现有密钥导入 Bitwarden
导入功能仅在 桌面应用 中可用：
- 点击 New → 选择 SSH key 类型。
- 复制你想导入的现有 SSH 密钥。
- 点击 Import key from clipboard（从剪贴板导入） 图标，系统会自动粘贴。
注意：目前仅支持 OpenSSH 或 PKCS#8 格式。从 Putty 导入的密钥暂不兼容。
配置 Bitwarden SSH Agent
要将 Bitwarden 设置为你的主要 SSH Agent，需要配置 SSH 客户端使其与 Bitwarden 通信进行身份验证。
Windows
要启用 Bitwarden SSH Agent，你必须先禁用 Windows 系统自带的 OpenSSH 服务。具体步骤如下：
- 在 Windows 系统中，搜索打开 服务，找到 OpenSSH Authentication Agent（可通过 Windows 搜索栏查找）。
Windows 服务面板
打开 OpenSSH Authentication Agent 属性 窗口，将 启动类型 设置为 已禁用。
禁用 OpenSSH
设置完成后，点击 应用，然后点击 确定。
macOS
macOS App Store 版本
启用 Bitwarden SSH Agent：
- 配置
SSH_AUTH_SOCK 环境变量，指向 Bitwarden SSH Agent 的 socket 文件。将 <user> 替换为你的用户名：
export SSH_AUTH_SOCK=/Users/<user>/Library/Containers/com.bitwarden.desktop/Data/.bitwarden-ssh-agent.sock
.dmg 下载版本（推荐）
- 配置
SSH_AUTH_SOCK 环境变量：
export SSH_AUTH_SOCK=/Users/<user>/.bitwarden-ssh-agent.sock
- 或者使用以下命令配置
SSH_AUTH_SOCKET：
launchctl setenv "SSH_AUTH_SOCKET" "/Users/<user>/.bitwarden-ssh-agent.sock"
注意：使用 launchctl 命令后，可能需要重启终端。
Shell 配置（适用于 .dmg 版本）
- 编辑你的 shell 配置文件：
nano ~/.bashrc
nano ~/.zshrc
- 在文件中添加：
export SSH_AUTH_SOCK=/Users/<user>/.bitwarden-ssh-agent.sock
Linux
- 配置
SSH_AUTH_SOCK 环境变量（将 <user> 替换为你的用户名）：
export SSH_AUTH_SOCK=/home/<user>/.bitwarden-ssh-agent.sock
Shell 配置
- 编辑配置文件：
nano ~/.bashrc
nano ~/.zshrc
- 添加以下内容：
export SSH_AUTH_SOCK=/home/<user>/.bitwarden-ssh-agent.sock
Snap 和 Flatpak 安装版本
配置对应的 socket 路径：
# Snap
export SSH_AUTH_SOCK=/home/<user>/snap/bitwarden/current/.bitwarden-ssh-agent.sock
# Flatpak
export SSH_AUTH_SOCK=/home/<user>/.var/app/com.bitwarden.desktop/data/.bitwarden-ssh-agent.sock
启用 SSH Agent
要在 Bitwarden 桌面应用中启用 SSH Agent，请进入 设置（Settings） 并开启 Enable SSH agent（启用 SSH Agent）。
启用 SSH Agent 后，你还可以调整 Ask for authorization when using SSH agent（使用 SSH Agent 时请求授权） 设置。该设置决定了 Bitwarden 何时要求你授权访问 SSH 密钥：
- Always（始终）
- Never（从不）
- Remember until vault is locked（记住直到保险库被锁定）
Always（始终） 是默认选中的选项。
测试 SSH 密钥
配置好 Bitwarden SSH Agent 后，你可以通过以下命令测试设置是否成功：
ssh-add -L
这将列出保存在 Bitwarden 中的 SSH 公钥。
提示：
- 保险库已锁定时：Bitwarden 会自动提示解锁。
- 保险库已解锁时：每次使用密钥都会弹出确认窗口。
使用 SSH 密钥通过 Git 进行身份验证
SSH 可用于 Git 身份验证。Bitwarden SSH Agent 可以为你的 Git 工作流增加安全性和便利性。在本示例中，Bitwarden SSH Agent 将用于向 GitHub 进行身份验证。
在你的 GitHub 账户中，前往 Settings（设置） → SSH and GPG keys，然后点击 New SSH Key（新建 SSH 密钥）。
在新增 SSH 密钥页面，填写 Name（名称），选择 Key type（密钥类型） 为 Authentication Key（认证密钥）。将 Bitwarden 保险库中的公钥 复制并粘贴到 GitHub 的 Key 字段中。
填写完所有字段后，点击 Add SSH key（添加 SSH 密钥） 保存。GitHub 会要求你验证账户。
在终端中测试 GitHub SSH 密钥（例如 macOS）：
ssh -T git@github.com
如果成功，Bitwarden 会弹出访问请求确认窗口。点击 Authorize（授权） 确认。成功后你会看到以下验证消息：
Hi <USER>! You've successfully authenticated, but GitHub does not provide shell access.
使用 SSH 密钥认证 Git 仓库
使用 Bitwarden SSH Agent 为 Git 提交进行 SSH 签名。在使用 Bitwarden SSH Agent 签名 Git 提交前，你的系统需要满足以下要求：
- Git 版本 2.34 或更高（使用
git --version 检查）
- OpenSSH 版本 8.8 或更高（使用
ssh -V 检查）
- 已启用 SSH Agent 的 Bitwarden 桌面客户端
配置 Git 使用 SSH 签名
你可以通过全局变量或在 .gitconfig 文件中进行配置。
设置全局变量：
设置 Git 使用 SSH 进行签名：
git config --global gpg.format ssh
指定用于签名的 SSH 密钥（使用 Bitwarden 时，将 <YOUR_PUBLIC_KEY> 替换为从 Bitwarden 复制的公钥）：
git config --global user.signingkey "<YOUR_PUBLIC_KEY>"
启用自动提交签名：
git config --global commit.gpgsign true
在 .gitconfig 文件中设置：
使用编辑器打开 .gitconfig 文件：
nano ~/.gitconfig
添加以下配置：
[gpg]
format = ssh
[user]
signingkey = "<YOUR_PUBLIC_KEY>"
name = <USER_NAME>
email = <USER_EMAIL>
[commit]
gpgsign = true
Windows 用户注意：
- 添加
core.sshCommand 配置使用 Microsoft OpenSSH。
- 可能还需要设置
gpg.ssh.program 参数。
为 Git 提交签名
在 GitHub 设置中添加用于签名的 SSH 密钥（选择 Signing Key 类型）。
配置 allowedSignersFile：
git config --global gpg.ssh.allowedSignersFile "$HOME/.ssh/allowed_signers"
将你的公钥添加到 allowed_signers 文件中：
# 创建文件
touch ~/.ssh/allowed_signers
# 编辑文件并添加（示例）：
User1@Bitwarden.com ssh-ed25519 <Your_Public_Key>
使用 SSH 方式克隆仓库：
git clone git@github.com:<USER>/<repository>.git
创建提交：
git commit -m "This commit is signed using SSH"
Bitwarden 会弹出授权提示。
授权后执行推送：
git push
你可以在 GitHub 的提交记录中验证签名。
SSH Agent 转发
SSH Agent 转发允许你登录的远程服务器使用你的密钥去认证其他服务器，而无需将私钥暴露到你的保险库之外。
示例（文件传输）：
确保 Bitwarden 桌面应用已启用 SSH Agent。
创建或导入 SSH 密钥。
使用 -A 参数建立连接：
ssh -A <HostnameA>
发送文件：
rsync -avzP ./TEST.txt <USER>@<HostnameB>:/home/<USER>/test.txt
Bitwarden 会弹出授权窗口，确认后完成文件传输。
官方文档原文：https://bitwarden.com/help/ssh-agent/
