SSH Agent

Streamline SSH access to your managed infrastructure with Keeper's built-in SSH agent

Overview

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

Key Features

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

Downloads

The Keeper Desktop application is available from the Download Page of our website.

Storing Keys in Keeper

In the Keeper vault, you can store the SSH private key two ways:

• Added as a custom field

• Attached as a file

Custom Field Example

File Attachment Example

In both scenarios, Keeper supports password-protected keys as long as the password is saved to the record password field.

PEM (Privacy-Enhanced Mail)

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

OpenSSH

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

PKCS#8

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

Benefits of SSH Agent

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.

Activating the SSH Agent

From the Keeper Desktop application, visit the Settings > Developer screen and manage the SSH Agent from this screen.

Developer Settings

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.

SSH Agent Settings

To enable SSH agent on specific keys, select those keys from the provided drop-down.

Limit SSH access to records

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.

• See Environment Setup

Using SSH Agent

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.

Using SSH Agent with Git

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.

• Integration with Git

Using SSH Agent with Tunnels

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.

SSH Agent with Tunnels

From the local terminal, paste the SSH command.

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.

SSH Agent Authorization Dialog

After access has been granted, the SSH connection is instantly established to the target system, through the encrypted Keeper tunnel.

Tunnel established with SSH Agent

---

Environment Setup

Linux and macOS

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:

Terminal Setup Command

For example:

export SSH_AUTH_SOCK='/path/to/keeper-ssh-agent.sock'

zsh (macOS)

• Edit the file ~/.zshrc

• Apply changes: source ~/.zshrc

bash

• Edit the file ~/.bashrc

• Apply changes: source ~/.bashrc

fish shell

• Edit the file ~/.config/fish/config.fish

• Add this line and save:

set -x SSH_AUTH_SOCK /path/to/keeper-ssh-agent.sock

• Apply changes:

source ~/.config/fish/config.fish

Verify the Configuration:

echo $SSH_AUTH_SOCK

You should see: /path/to/keeper-ssh-agent.sock

You may need to open a new shell for this to take effect.

---

Windows

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.

SSH Agent on Windows

When establishing a connection to the target through PowerShell, Keeper will prompt for permission.

Allow Access Dialog

Windows Note on SSH Agent Conflicts

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 Disabled

Once stopped, Keeper’s agent will take over and handle all ssh and git operations using keys stored securely in your vault.

---

Rotation of SSH Keys

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