SSH Agent

The Bitwarden SSH agent securely encrypts and stores your SSH (Secure Shell) keys for use to:

• Authenticate to servers

• Sign Git commits

• Interact with SSH based services

The Bitwarden SSH agent will organize and protect your keys in one secure location. SSH keys can be accessed and generated using the desktop app, web app, browser extension, and mobile app.

New SSH keys can be created and saved in the Bitwarden desktop app. Bitwarden SSH keys will store:

SSH keys stored in the Bitwarden Password Manager will have access to Bitwarden features such as folders, favorites, master password re-prompt, notes, cloning items, attachments, and custom fields.

Create a new SSH key must be done using the Bitwarden desktop app, web app, mobile app, or browser extension. Once created, SSH keys stored in Bitwarden can be accessed from the desktop app, web app, and mobile apps.

1. Select the New button and choose SSH key as the item type.
   

   

   note

   At this time, Bitwarden can only generate ED25519 type SSH keys.

2. Fill in remaining details such as Name and select the  Save icon once complete.

Once an SSH key has be saved in your Bitwarden vault, you may edit the key using the Bitwarden desktop app or mobile client. To edit an SSH key:

Existing SSH keys can be imported into Bitwarden.

1. Select  SSH key from the navigation menu.

2. 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.
   

   

   note

   Imported keys must be in OpenSSH or PKCS#8 format

   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 SSH agent on your Bitwarden desktop app, navigate to Settings and Enable SSH agent.

Once the SSH agent has been configured for Bitwarden, we can test the setup by requesting an SSH list:

BashCopy
ssh-add -L

This will return a list of SSH keys saved in your Bitwarden desktop client.

SSH can be used to authenticate with Git. The Bitwarden SSH agent can add security and ease of use to your Git workflows. In this example, the Bitwarden SSH agent will authenticate to GitHub.

1. On your GitHub account, setup an SSH key by navigating to Settings, SSH and GPG keys, then select New SSH Key.
   

   

2. On the add new SSH key screen, add a Name, select a Key type. Choose Authentication Key for authenticating GitHub session. Copy & paste the Public key from your Bitwarden vault into the Key field on GitHub.
   

   

3. 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.

4. Test the GitHub SSH key in your terminal, for example if you are using macOS:
   

   BashCopy
   ssh git@github.com

5. If successful, Bitwarden will prompt you to verify access request. Select Authorize to confirm. If successful, you will receive a message verifying the authentication attempt:
   

   BashCopy
   Hi <USER>! You've successfully authenticated, but GitHub does not provide shell access.

Use the Bitwarden SSH agent to sign SSH Git commits. Before using the Bitwarden SSH agent to sign Git commits, your system requires:

• Git version 2.34 or newer. Check your Git version with:
  

  BashCopy
  git --version

• OpenSSH version 8.8 or newer. Check version with:
  

  BashCopy
  ssh -V

• Bitwarden desktop client with SSH agent enabled.
  

Configure your Git environment to point to your SSH key for signing. To complete this you may set global variables or establish the instructions in your .gitconfig file.

Set global variables

To configure Git settings using --global variables:

1. Set Git to use SSH for signing:
   

   BashCopy
   git config --global gpg.format ssh

2. Specify the SSH key to use as the singing key. To use the Bitwarden SSH agent, replace /YOUR/PUBLIC/SSH/KEY with the public key copied from the SSH key saved in your Bitwarden vault.
   

   BashCopy
   git config --global user.signingkey "<YOUR_PUBLIC_KEY>"

Set .gitconfig file

To configure Git using a .gitconfig file:

1. Access .gitconfig with your preferred text editor:
   

   BashCopy
   nano ~/.gitconfig

2. Add the following configurations:
   

   BashCopy
   [gpg]
           format = ssh
   [user]
           signingkey = "<YOUR_PUBLIC_KEY>"
           name = <USER_NAME>
           email = <USER_EMAIL>
   [commit]
           gpgsign = true
   

Using SSH to authenticate with Git can add security and ease of use to your workflow. Similarly, SSH keys stored in Bitwarden can be used to sign and verify Git commits using SSH protocol. In this example, the Bitwarden SSH agent will be used to sign Git commits to GitHub.

1. On your GitHub account, setup an SSH signing key by navigating to Settings, SSH and GPG keys, then select New SSH Key.

2. 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.
   

3. Use the SSH key to clone your repository with SSH method:
   

   

   BashCopy
   git clone git@github.com:<USER>/<repository>.git

4. Create the Git commit using terminal or your preferred text editor:
   

   BashCopy
   git commit -m "This commit is signed using SSH"

5. Bitwarden will prompt you to authorize the key usage:
   

   

6. Once authorized, the SSH key will be initiated to approve the commit. You may now push the commit:
   

   BashCopy
   git push

7. You may verify your commit on Github by navigating to GitHub commits:

   

Once your SSH agent has been configure, see advanced use cases for more SSH client functions.