Passwordless Git Authentication on Windows

Introduction

In this post, I’ll show you how to set up passwordless SSH authentication on Windows by configuring an SSH agent. This can be used for all your Git pushing and pulling, as well as any other SSH sessions you initiate.

This article assumes that you already have an SSH key pair and you use it to authenticate to remote systems, such as GitHub. It also assumes that your key pair is encrypted with a passphrase, which it definitely should be, and that you are tired of entering that passphrase every time you initiate an SSH session. That should be pretty much every Windows user who uses Git or administers Linux/UNIX systems.

What we’ll do is set up an SSH agent. An SSH agent is a tool that holds your key in memory, unencrypted, and ready to be used by SSH without having to decrypt it every time it is used. On Linux/UNIX, there are several options for and SSH agent, including ssh-agent, gpg-agent, openssl-agent, and others.

Background

There are several implementations of the SSH protocol in existence today. The reference implementation comes from the OpenBSD project and is called OpenSSH. That’s right - the SSH everyone uses on Linux comes to us from OpenBSD!

On Windows, there are fewer options. OpenSSH has been available as an optional feature since Windows 10 build 1809 and Windows Server 2019. It is possible to use the Microsoft-packaged OpenSSH with Git, and it includes ssh-agent, but I’m going to show you another way.

This method uses the OpenSSH client included with Cygwin, along with Pageant, the SSH agent included with PuTTY. Many of you have probably been using PuTTY since long before Microsoft started including OpenSSH in Windows, but you may not be using Pageant.

Setup

Set up Cygwin and OpenSSH

Follow these instructions to set up Cygwin and Git: A Better Git for Windows

Set up Pageant

PuTTY expects SSH keys in a format other than the PEM format that OpenSSH uses. Before using Pageant, we need to convert our SSH key to the PuTTY .ppk format. It’s the same key, same cryptographic material, just a different on-disk format.

  1. Install PuTTY You can download PuTTY from their website. I use Chocolatey, but use whatever method you prefer. Technically, we only need pageant and puttygen, if you want a minimal installation.

  2. Open puttygen

Step one

  1. Click the Load button and select your existing SSH private key. It is usually in your home directory and called .ssh/id_rsa. The file selection dialog only shows .ppk files initially, so be sure to change the filter to All Files (*.*).

  2. Once the file is selected, enter your passphrase to decrypt the key. Don’t worry, the .ppk file will still be encrypted on disk.

Step three

  1. With your key successfully loaded, set the passphrase by filling in the fields for Key passphrase and Confirm passphrase. This can be the same passphrase used to encrypt the PEM-format key. It may avoid some confusion to use the same passphrase to encrypt both key formats.

  2. Click Save private key to store it in .ppk format. I store the .ppk file under .ssh, but you can store it anywhere.

Set Pageant to Auto-start

Microsoft seems to make this harder with each version of Windows, but next we need to set Pageant to auto-start in Windows 11. If this part seems unnecessarily complicated, please direct your wrath at Microsoft.

  1. Open a File Explorer window and navigate to the pageant.exe executable file (wherever you installed it). Keep this first window open

  2. Right-click on Start and select Run

  3. In the Run dialog box, type either shell:startup and select Enter.

  4. A second File Explorer window opens, containing a list of applications that start automatically when a user signs in.

  5. Right-click on the pageant.exe file in the first window, and drag and drop it to the second window.

  6. In the context menu that appears, click Create shortcuts here.

  7. Right click on the newly created shortcut and select Properties

  8. Edit the Target field to include the absolute path to the .ppk file you created above as an argument to the executable file. For example, I installed Pageant using Chocolatey, so my Target field was set to this:

C:\ProgramData\chocolatey\bin\PAGEANT.EXE

Modify the target field to include the path to your .ppk file, like this:

C:\ProgramData\chocolatey\bin\PAGEANT.EXE C:\Users\amendlik\.ssh\amendlik.ppk

  1. Double click on the short cut now to start Pageant. It will start automatically the next time you logon.

  2. If everything is set up correctly, it will prompt you for your passphrase to decrypt your SSH key.

Install the SSH agent

Next, we will install ssh-pageant-git. This is the SSH agent that will allow any SSH sessions initiated from the Cygwin-packaged OpenSSH client, including Git, to access your private key held by Pageant. Even though the package has -git in the name, it works for any SSH session.

  1. Launch your msys2.exe console and run the following command:
$ pacman -Sy ssh-pageant-git

Shell Configuration

The last step is to modify your shell configuration file to use the SSH agent. The procedure is the same for all shells, but the exact syntax will vary. The steps are as follows:

  1. Start or reuse the SSH agent. There needs to be exactly one SSH agent running for a user, so when the shell starts it needs detect if ssh-agent is already running. If it is not running, start it. Fortunately ssh-agent has the -r (reuse) option that handles this automatically.

  2. Set the SSH_AUTH_SOCK environment variable to the value of the socket file that ssh-agent is using.

I use Fish shell, but I’ll provide the syntax for the shells I know.

Bourne and Bourne-like Shells (sh, dash, bash, etc.)

Add the following to ~/.profile:

# Start or re-use a pageant-agent.
/usr/bin/ssh-pageant -r -a "/tmp/.ssh-pageant-$USERNAME" > /dev/null

# Set the socket for the SSH agent
export SSH_AUTH_SOCK="/tmp/.ssh-pageant-$USERNAME"

Fish

Add the following to ~/.config/fish/config.fish:

# Start or re-use a pageant-agent.
/usr/bin/ssh-pageant -r -a "/tmp/.ssh-pageant-$USERNAME" > /dev/null

# Set the socket for the SSH agent
set -g -x SSH_AUTH_SOCK "/tmp/.ssh-pageant-$USERNAME"