SSH agent forwarding with 1Password

SSH agent forwarding lets you make SSH requests within a remote environment as if it were your local machine, like running Git commands and signing commits from a cloud development environment or remote workstation.

Instead of storing your private keys on the remote host, you can use SSH agent forwarding to forward your requests to your local 1Password SSH Agent. Then authorize the request with biometrics without your private keys ever leaving the local 1Password process.

Requirements

1. Install and sign in to 1Password for Mac or Linux.
2. Import or generate SSH keys in 1Password.
3. Set up the 1Password SSH Agent and make sure it's running on your local machine.

If you use Windows

If you use a Windows computer, you can set up the 1Password WSL integration to authenticate SSH requests in your WSL instance from your Windows host.

About SSH agent forwarding

When you enable agent forwarding for a remote host, every SSH request you make within the remote environment gets forwarded to the local 1Password process over the 1Password SSH Agent socket.

You can authorize SSH requests locally using options you've set up in 1Password, like your fingerprint. Then your authorization gets forwarded back to the remote host without ever needing to provide your private key to the remote server.

caution

Make sure you only use SSH agent forwarding with trusted hosts. Learn how to use SSH agent forwarding more securely.

Set up SSH agent forwarding

SSH agent forwarding is turned off in OpenSSH by default. You can choose to turn it on for a single session or for a specific host.

For a single session

To turn on agent forwarding for a single session only, use the -A flag with the ssh command:

When you're connected to the remote host with agent forwarding turned on, the SSH_AUTH_SOCK environment variable on the remote host is automatically set. Data sent over this socket gets forwarded to the local 1Password socket.

See result...

To check if agent forwarding is working, run the following command view a list of the SSH keys forwarded from 1Password to the remote host:

See result...

If you see your SSH key listed, try to run an SSH request from within the remote server:

The 1Password app on your local machine should prompt you to authorize the request.

For a specific host

If you want to set up SSH agent forwarding for a specific host all the time so you don't need to use the -A flag for each session, edit your ~/.ssh/config file to include that host:

SSH agent forwarding security

Security considerations

When you authorize your local terminal, IDE, or other SSH client to use an SSH key in an agent forwarding session, any new connection made within the remote environment using the same key is also authorized. If someone else were to gain access to the remote environment as the same OS user, they'd be able to use the SSH key to authenticate connections from the remote host for the duration of the session.

However, any other SSH keys available in the remote environment still require your approval before they can be used. Unlike the standard OpenSSH agent, where every key in the agent can be used in the remote environment without additional authorization, the 1Password SSH Agent requires your approval for each SSH key before it can be used. An attempt to use one of those keys from the remote environment triggers a 1Password authorization prompt that needs to be authenticated, making agent forwarding more secure with 1Password than with the OpenSSH agent.

Use agent forwarding more securely

We recommend the following:

• Only use agent forwarding when you need it and in environments that you trust are secure.

• Set up agent forwarding on a per-command basis or configure your ~/.ssh/config file to allow agent forwarding only with specific hosts. Do not turn on SSH agent forwarding for all hosts by default.

  ~/.ssh/config (bad 👎)

  We recommend that you always scope the ForwardAgent yes directive down to a specific host or domain you trust for agent forwarding. For example, to turn on agent forwarding for Gitpod :

  ~/.ssh/config (good 👍)

Use case: Cloud Development Environment

If you use a local integrated development environment (IDE) to connect to a cloud development environment (CDE) and you want to pull, push, and sign remote Git commits, you can authenticate those commands through the local 1Password SSH Agent.

For example, you might have an IDE desktop app on your local workstation that you use to authenticate into a cloud-based development environment. You want to use the the CDE workspace to access remote Git repositories and you need to be able to authenticate Git requests and sign commits. With SSH agent forwarding, you can authenticate SSH and Git commands from your CDE workspace in your IDE desktop app through the 1Password SSH Agent running on your local workstation.

Set up SSH agent forwarding

To set up SSH agent forwarding so you can authorize Git requests from your cloud development environment, edit your SSH config file to add your CDE host. The remote development integration in your IDE should recognize this automatically.

To check if agent forwarding is correctly set up, open a remote shell in your IDE then run the following command:

See result...

You should see a list of the SSH keys the agent can use for SSH requests.

Use SSH for Git authentication

If your CDE is set up to use HTTPS to authenticate with Git and you want to use SSH instead, run the following command to modify the remote Git configuration for the CDE:

Alternatively, you can add the command to your cloud development initialization (cloud-init) script or dotfiles.

The next time you make a Git request from your CDE, 1Password should prompt you to authorize the request. For example:

If you only want to use SSH authentication going forward, you may want to revoke HTTPS write access to your repository.

Set up Git commit signing

Your local .gitconfig file isn't automatically forwarded to your cloud development environment, so you'll need to modify the Git configuration in your CDE to set up remote Git commit signing.

1. Configure Git to use SSH for commit signing:

2. Tell Git to always sign commits:

3. Set the SSH key you want to use to sign commits:

Authorization model

When you run an SSH or Git request in your cloud development environment that requires authorization, 1Password will prompt you to approve SSH key usage for the IDE that's connected to your CDE. If you approve the request, the entire IDE will be authorized to use that key. Any process running on the cloud development environment under the same OS user will also be authorized, which is a security consideration to keep in mind.

Use case: Remote workstation

If you have a remote workstation that you connect to over SSH, and you want to run SSH and Git requests from that workstation, you can authenticate those requests through the 1Password agents that runs on your local host.

For example, you might have a desktop workstation at home that contains all your Git repositories. You want to work on the go, so you use your laptop to connect to your remote workstation over SSH so you can work in your Git repos. With SSH agent forwarding, you can authenticate SSH and Git commands from your remote workstation through the 1Password SSH Agent running on your local laptop.

Set up SSH agent forwarding

To set up SSH agent forwarding so you can authorize SSH and Git requests from your remote workstation, edit the SSH config file on your local host to allow agent forwarding with your remote workstation.

To check if agent forwarding is correctly set up, connect to your remote workstation then run the following command:

See result...

You should see a list of the SSH keys the agent can use for SSH requests.

Modify the IdentityAgent configuration on the remote workstation

If your remote workstation also has the 1Password SSH Agent installed, you'll want to make sure that Git and SSH use the forwarded socket from your local host instead of the agent socket for the 1Password app installed on the remote workstation.

The IdentityAgent takes precedence over the SSH_AUTH_SOCK environment variable, so you may want to modify the ~/.ssh/config file for your remote workstation so the IdentityAgent setting is only applied if you're not in an SSH shell.

Then any Git or SSH command executed from an SSH shell on the remote workstation will use the forwarded SSH_AUTH_SOCK for authentication and 1Password should prompt you to authorize SSH requests from your local host.

This change won't affect how the 1Password SSH Agent runs when you use the workstation locally instead of accessing it remotely. The IdentityAgent setting will be applied as usual to use the SSH agent running on the workstation.

Set up Git commit signing

Your local .gitconfig file isn't automatically forwarded to your remote workstation, so the remote Git configuration will be used by default.

If you've configured Git commit signing with 1Password on the remote workstation using the same SSH key you use on your local host, you shouldn't need make any changes to your setup.

If the op-ssh-sign signing program finds that both the SSH_AUTH_SOCK and the SSH_TTY environment variables are set, it will automatically adapt to use the forwarded socket from your local host instead of the 1Password socket from your remote workstation.

Authorization model

When you run an SSH or Git request from a remote shell or remotely connected IDE that requires authorization, 1Password will prompt you to approve SSH key usage for the terminal or IDE you use to connect to the remote workstation.

If you approve the request, the entire app will be authorized to use this key. Any process running on the remote workstation under the same OS user will also be authorized, which is a security consideration to keep in mind.

Troubleshooting

If you're having trouble using agent forwarding with the 1Password SSH Agent, there are a few things you should check.

Check if the SSH_AUTH_SOCK environment variable is set

Run echo $SSH_AUTH_SOCK in the terminal to make sure the environment variable is set on your server.

See result...

If the variable isn't set, SSH agent forwarding won't work. Make sure the 1Password SSH Agent is turned on and that you've configured your SSH client to use the agent for authentication.

Check if the SSH agent can access the correct SSH key

Run ssh-add -l in the terminal to see a list of the SSH keys forwarded from 1Password to the remote host:

See result...

If you don't see your SSH key listed, make sure the key is eligible to use with the 1Password SSH Agent and that it's saved in a vault the SSH agent is configured to use.

Check if agent forwarding is allowed on the server

To use agent forwarding with a remote server, the AllowAgentForwarding option must be set to Yes in the sshd_config file for the server.