SSH Agent
The Bitwarden desktop app has the capability to store and manage Secure Shell (SSH) keys for encrypted access to servers and application interfaces. The Bitwarden SSH agent can list and use SSH keys stored in the Bitwarden vault.
With the Bitwarden desktop app, the SSH feature will allow users to create new SSH keys or import existing keys to the Bitwarden vault.
To enable SSH storage on your Bitwarden desktop app, navigate to Settings and Enable SSH agent.
New SSH keys can be created and saved in the Bitwarden desktop app UI. Bitwarden SSH keys will store:
Field | Description |
|---|---|
Key name | The name for your SSH key. |
Private key | The private key is sensitive data that will be used by the server to facilitate secure connection. Private key data should be treated with care and kept secure. Users may use Bitwarden to generate a secure, unique private key. |
Public key | Portion of the key shared with the server that you will be connecting to. |
Fingerprint | A short unique sting generated from the public key used to identify the key. For example, SSH-signed git commits can be verified using the fingerprint. |
SSH keys stored in the Bitwarden password manager will have access to Bitwarden features such as folders, collections, favorites, master password re-prompt, notes, attachments, and custom fields.
Select the New button and choose SSH key as the item type.
Create new SSH key on desktop client note
At this time, Bitwarden can only generate
ED25519type SSH keys.Fill in remaining details such as Name and select the Save icon once complete.
Existing SSH keys can be imported into Bitwarden.
Select SSH key from the navigation menu.
Copy the existing SSH key you wish to import into Bitwarden. Use the Import key from clipboard button. This will automatically paste the SSH key into Bitwarden.
Import SSH key on desktop client note
Imported keys must be in OpenSSH or PKCS#8 formats and cannot be password protected. Additionally, at this time, Imported SSH keys from Putty are not compatible.
In order to use Bitwarden as your primary SSH agent, you will be required to configure your SSH client to communicate with Bitwarden for authentication.
To enable the Bitwarden SSH agent on Windows, you must disable the OpenSSH service on your Windows machine. To disable OpenSSH:
On your Windows machine, navigate to Services → OpenSSH Authentication Agent. The Administrator services window can be accessed using the Windows + R run command.
Once you have opened the OpenSSH Authentication Agent Properties window, Set the Startup type setting to Disabled.
note
If OpenSSH Authentication Agent is not an option in the Services list, there is no need to disable the service.
Enable the Bitwarden SSH agent on MacOS:
Export the
SSH_AUTH_SOCKvariable and set it tobitwarden.ssh-agent.sock. In the following example, replace<user>with your username:Bashexport SSH_AUTH_SOCK=/Users/<user>/.bitwarden-ssh-agent.sock
Enable the Bitwarden SSH agent on Linux:
Export the
SSH_AUTH_SOCKvariable and set it tobitwarden.ssh-agent.sock. In the following example, replace<user>with your username:Bashexport SSH_AUTH_SOCK=/Users/<user>/.bitwarden-ssh-agent.sock
Once the SSH agent has been configured for Bitwarden, we can test the setup by requesting an SSH list:
Bashssh-add -L
This will return a list of SSH keys saved in your Bitwarden desktop client.
note
When accessing an SSH key, the behavior of Bitwarden will differ depending on the lock or unlock status of the client.
Locked vault: If your Bitwarden vault is locked, it must first be unlocked in order to gain access to the SSH key. This can be done by logging into the desktop app or unlocking the vault if it is open in locked state.
Unlocked vault: If the desktop vault is unlocked, you will be prompted to confirm the SSH key usage.
Connect to GitHub with SSH:
Import or create a new SSH key on the Bitwarden desktop client. See here for more information to create an SSH key.
On your GitHub account, setup an SSH key by navigating to Settings, SSH and GPG keys, then select New SSH Key.
Create new GitHub SSH key On the add new SSH key screen, add a Name, select a Key type. Choose
Authentication Keyfor authenticating GitHub session. Copy & paste the Public key from your Bitwarden vault into the Key field on GitHub.
Create new GitHub key Once you have completed all of the fields, select Add SSH key to save the key. GitHub will request you verify your GitHub account before the key is saved.
Test the GitHub SSH key in your terminal, for example if you are using macOS:
Bashssh git@github.com
Use the Bitwarden SSH agent to sign SSH Git commits. In order to sign SSH commits, there are a few perquisites:
Git version 2.34 or later. You may check your Git version with:
Bashgit --versionOpenSSH version 8.8 or newer. Check version with:
Bashssh -VBitwarden desktop client with SSH agent enabled.
Set Git to use SSH for signing:
Bashgit config --global gpg.format sshSpecify the SSH key to use as the singing key. To use the Bitwarden SSH agent, replace
/YOUR/PUBLIC/SSH/KEYwith the public key copied from the SSH key saved in your Bitwarden vault.Bashgot config --global user.signingkey /YOUR/PUBLIC/SSH/KEY
On your GitHub account, setup an SSH key by navigating to Settings, SSH and GPG keys, then select New SSH Key.
On the add new SSH key screen, add a Name, select a Key type. Choose
Signing Key. Copy & paste the Public key from your Bitwarden vault into the Key field on GitHub.Use the SSH key to clone your repository with SSH method:
SSH clone Bashgit clone git@github.com:<USER>/<repository>.gitTo commit and push code with standard Git practices:
Bashgit commit -m "This commit is signed using SSH"If your Bitwarden vault is unlocked, select Authorize on the Bitwarden desktop client. If you vault is locked, you will be prompted to unlocked your vault. Select Authorize to continue:
Authorize SSH with client Once authorized, the SSH key will be initiated to approve the commit. You may now push the commit:
Bashgit push
Suggest changes to this page
How can we improve this page for you?
For technical, billing, and product questions, please contact support