Streamline SSH access to your managed infrastructure with Keeper's built-in SSH agent
The Keeper Desktop application includes a built-in SSH agent, enhancing the security and convenience of managing SSH keys and connections. This feature simplifies secure access to target systems, eliminates the need to store SSH keys locally, and supports seamless integration with Keeper's robust key management and rotation capabilities. This SSH Agent capability is available to all Keeper users.
Keeper Desktop and SSH Agent is available for all platforms:
Windows
macOS
Linux
Built-in SSH Agent: Automatically embedded into the Keeper Desktop application for any private keys, eliminating the need for third-party SSH agents.
No Local Key Storage: SSH keys are securely stored and managed in Keeper, removing the risk of key exposure on local machines.
Seamless Authorization: Securely authorize SSH access to target systems when the Keeper vault is unlocked.
Local and Remote Use: Supports SSH connections to line-of-sight targets in addition to managed systems via KeeperPAM tunnels.
Git Integration: Authenticate with Github and Gitlab, and sign your Git commits without having to store private keys locally on the workstation.
Encrypted keys: SSH private keys held in Keeper can be encrypted with a passphrase, adding an additional layer of protection. Keeper enhances this by allowing the record's password field to act as the passphrase, ensuring seamless security and usability.
Key Rotation: Keeper's automatic SSH key rotation works seamlessly with the SSH agent to ensure that the latest keys are always available for use.
The Keeper Desktop application is available from the Download Page of our website.
In the Keeper vault, you can store the SSH private key two ways:
Added as a custom field
Attached as a file
In both scenarios, Keeper supports password-protected keys as long as the password is saved to the record password field.
A base64-encoded format typically used for private keys. It is commonly used with OpenSSL and older OpenSSH versions. Example:
-----BEGIN RSA PRIVATE KEY-----
(Base64-encoded data)
-----END RSA PRIVATE KEY-----The default format for keys generated by the ssh-keygen utility in modern versions of OpenSSH (>=7.8). It uses a custom serialization format for private keys. Example:
-----BEGIN OPENSSH PRIVATE KEY-----
(Base64-encoded data)
-----END OPENSSH PRIVATE KEY-----A standardized format for encoding private keys that supports multiple key types. Often used with OpenSSL or for interoperability. Example:
-----BEGIN PRIVATE KEY-----
(Base64-encoded data)
-----END PRIVATE KEY-----The SSH Agent embedded within the Keeper application allows keys stored securely in Keeper to be seamlessly used by your computer.
The SSH protocol works by cycling through all loaded keys in the agent until it finds a match with the server. However, OpenSSH imposes a default limit on the number of keys the agent can try during a single authentication attempt, which is typically 6 keys. This limitation is defined by the MaxAuthTries parameter in SSH configurations and is not something Keeper can directly control.
To address this, Keeper has implemented enhancements to optimize key usage. For example, when you activate a Tunnel associated with a specific resource, Keeper ensures that the key for that Tunnel is immediately activated by the agent. If the maximum limit of active keys is reached, Keeper prioritizes the relevant key by moving it to the top of the agent's list, ensuring it is used for the connection.
From the Keeper Desktop application, visit the Settings > Developer screen and manage the SSH Agent from this screen.
When you enable the SSH Agent, all of the specified SSH keys stored in Keeper will be available to your local machine while the vault is unlocked.
Select "Launch SSH Agent on startup" to activate the SSH agent upon every login.
To enable SSH agent on specific keys, select those keys from the provided drop-down.
In order to work with the local operating system (Linux, macOS and Windows), follow the guide below to enable SSH Agent for your operating system.
In its simplest use case, you can store the SSH key in Keeper. When you use an SSH client on your computer for any operation requiring a private key, Keeper's SSH Agent—integrated into the Keeper desktop application—will activate and prompt the user to authorize the request, provided the vault is unlocked.
The Keeper SSH Agent allows you to seamlessly authenticate into services like GitHub and securely sign Git commits. To help you get started, we've created a step-by-step guide on setting up authentication with GitHub and signing Git commits using Keeper.
For zero-trust Tunnel connections through a target resource, Keeper's SSH agent will automatically authenticate the session.
After a tunnel has been activated on a PAM resource, the SSH Command will display beneath the tunnel information.
If the Keeper SSH Agent has not yet been activated, clicking on the SSH Command (?) help dialog will display a link to open the SSH Agent configuration screen.
From the local terminal, paste the SSH command.
On your desktop computer, the Keeper Desktop will launch an authorization request that contains the key which is being requested. To authorize the request, click Authorize. To authorize subsequent requests for this key, select the "Don't ask again" option.
After access has been granted, the SSH connection is instantly established to the target system, through the encrypted Keeper tunnel.
On macOS and Linux, Keeper’s SSH Agent runs as a background process when the user unlocks their vault. To enable communication with SSH tools like ssh, git, or ssh-add, the user must set the SSH_AUTH_SOCK environment variable to point to the Keeper Agent’s Unix domain socket.
To use the Keeper SSH Agent from Linux or macOS environments, copy and paste the command to your shell's startup file:
For example:
export SSH_AUTH_SOCK='/path/to/keeper-ssh-agent.sock'zsh (macOS)
Edit the file ~/.zshrc
Apply changes: source ~/.zshrc
Edit the file ~/.bashrc
Apply changes: source ~/.bashrc
Edit the file ~/.config/fish/config.fish
Add this line and save:
set -x SSH_AUTH_SOCK /path/to/keeper-ssh-agent.sockApply changes:
source ~/.config/fish/config.fishecho $SSH_AUTH_SOCKYou should see: /path/to/keeper-ssh-agent.sock
You may need to open a new shell for this to take effect.
Keeper’s SSH Agent integrates with the Windows OpenSSH client by implementing the standard ssh-agent protocol over a named pipe, just like the native OpenSSH agent on Windows.
When the Keeper vault is unlocked:
The agent starts and listens on a Windows named pipe.
OpenSSH-based tools like ssh, ssh-add, git, and others detect the pipe and interact with Keeper's agent without needing local key files.
The agent responds to authentication requests, signing operations, and key listings as defined by the standard ssh-agent protocol.
This provides full OpenSSH compatibility on Windows, enabling:
Agent forwarding
SSH key signing
Passwordless login using keys stored securely in Keeper
Git commit signing and similar dev workflows
The Windows SSH Agent service will start up as soon as it is activated from The Keeper Desktop SSH Agent screen.
When establishing a connection to the target through PowerShell, Keeper will prompt for permission.
If the OpenSSH Agent service is currently running on Windows, you’ll need to stop it before using Keeper’s SSH Agent. Both agents listen on the same named pipe (\\.\pipe\openssh-ssh-agent), and only one can be active at a time.
To stop the built-in OpenSSH agent:
Stop-Service ssh-agent
Set-Service ssh-agent -StartupType DisabledOnce stopped, Keeper’s agent will take over and handle all ssh and git operations using keys stored securely in your vault.
KeeperPAM provides automatic rotation of SSH keys on-demand or on a scheduled basis.
See the Password Rotation section and the Linux User SSH Key use case
Keeper SSH Agent integration for Git Authentication and Commit Signing
Keeper's SSH Agent integrates seamlessly with Git for authentication and commit signing, ensuring private keys are securely stored in the Keeper Vault instead of being saved locally on the device. This approach enhances security by protecting sensitive keys from local exposure.
In this guide, we'll create and configure separate authentication and signing keys for use with GitHub, all managed securely by Keeper. Using distinct keys for authentication and signing helps maintain a clear separation of roles, further strengthening your security posture.
Ensure that SSH Agent is active on the Keeper Desktop
Terminal Configuration is performed
To authenticate with GitHub using Keeper, follow the below steps.
Generate SSH key on your terminal with the password generated by Keeper. For example:
ssh-keygen -t ecdsa -b 521 -C "[email protected]"
Enter passphrase (empty for no passphrase): *********
Enter same passphrase again: *********This will create the public and private keys locally on your machine.
For example:
/Users/craig/.ssh/id_ecdsa
/Users/craig/.ssh/id_ecdsa.pubThis immediately will trigger a Keeper dialog to authorize the Github Authentication key.
Clicking "Authorize" will use the key stored in Keeper to authenticate with Github.
Your setup is complete.
To sign GitHub commits with Keeper, we will create a separate key that is specifically used for the signing process. Follow the steps below.
Generate SSH key on your terminal with the password generated by Keeper. For example:
ssh-keygen -t ecdsa -b 521 -C "[email protected]"
Enter passphrase (empty for no passphrase): *********
Enter same passphrase again: *********This will create the public and private keys locally on your machine.
For example:
/Users/craig/.ssh/id_ecdsa
/Users/craig/.ssh/id_ecdsa.pubWe will only delete the local private key, since it is now stored and managed by Keeper. The public key (xxx.pub) needs to stay, as it will be used for identifying which key to use for signing.
rm /Users/craig/.ssh/id_ecdsaLet's also rename the public key to something more specific:
cd ~/.ssh
mv id_ecdsa.pub git_signing_key.pubPlace the username and the contents of the public key into a file called ~/.ssh/allowed_signers. For example:
[email protected] <contents of git_signing_key.pub>In this example, the file looks like this:
[email protected] ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAIbmlzdHA1MjEAAACFBAD2VeqOZ9bk2ABF6AZ63qJY2sDfz0kJJPfDW0zpres0/p1YGGJBYtyU4l3nIgwx0K2iEKFty429N2NNfIMBsqI+ngDq3/VGaexmZxymJnCzOl9+J1IQr6u05jZHLsk1FOALjOSm9jv4bF/DyK4oh5shKMlTHAeDWPfqMd3JwncSYBzKfA== [email protected]From the terminal, instruct Github to sign commits using this new key and allowed signers.
git config --global user.signingkey ~/.ssh/git_signing_key.pub
git config --global gpg.format ssh
git config --global commit.gpgsign true
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signersThis basically has the effect of adding several lines to ~/.gitconfig and applies the changes globally. You can also configure individual repos instead of making these changes globally.
From a repository, let's do a quick empty commit to test the signing process:
git commit --allow-empty -m "Test commit with SSH signing"This immediately will trigger a Keeper dialog to authorize the key.
To verify that the signature was applied to the commit, run the following:
git log --show-signatureThe response will display something like this:
commit 52319faf2e7c02a (HEAD -> main)
Good "git" signature for [email protected] with ECDSA key SHA256:xxxxxxx
Author: Craig Lurey <[email protected]>
Date: Fri Jan 17 20:18:19 2025 -0800
Test commit with SSH signingSetup is complete.
