Using SSH Agent Forwarding

To simplify deploying to a server, you can set up SSH agent forwarding to securely use local SSH keys. It allows you to use your local SSH keys instead of leaving keys (without passphrases!) sitting on your server.

You need to be familiar with ssh-agent.

• It’s a program that runs in the background and keeps your key loaded into memory, so that you don’t need to enter your passphrase every time you need to use the key.
• you can choose to let servers access your local ssh-agent as if they were already running on the server.
• This is sort of like asking a friend to enter their password so that you can use their computer.

See Steve Friedl’s Tech Tips guide

• Setting up SSH agent forwarding
  • Ensure that your own SSH key is set up and working

    See our guide on generating SSH keys

    You can test that your local key works by entering:

    $ ssh -T git@github.com
    # Attempt to SSH in to github
    > Hi username! You've successfully authenticated, but GitHub does not provide
    > shell access.
    

    Test local key

  • Now set up SSH to allow agent forwarding to your server.
    1. Open up the file at ~/.ssh/config
    2. Enter the following text into the file:

       Host example.com [your server's domain name]
         ForwardAgent yes
       

       Warning

       You may be tempted to use a wildcard like ‘Host *’ to just apply this setting to all SSH connections. That’s not really a good idea, as you’d be sharing your local SSH keys with every server you SSH into. They won’t have direct access to the keys, but they will be able to use them as you while the connection is established

       You should only add servers you trust and that you intend to use with agent forwarding.

• Testing SSH agent forwarding

  To test that agent forwarding is working with your server, you can SSH into your server and run ssh -T git@github.com once more. If all is well, you’ll get back the same prompt as you did locally.

  If you’re unsure if your local key is being used, you can also inspect the ‘SSH_AUTH_SOCK’ variable on your server:

  $ echo "$SSH_AUTH_SOCK"
  # Print out the SSH_AUTH_SOCK variable
  > /tmp/ssh-4hNGMk8AZX/agent.79453
  

  If the variable is not set, it means that agent forwarding is not working.

• Troubleshooting SSH agent forwarding

  See guide