Set up SSH Authentication Agent

Objectives

1. Create a batch file to automatically launch Pageant whenever you log into your computer.
2. Convert openSSH keys into PuTTY's private key file format.
3. Load private keys into Pageant's keyring.

Prerequisites

1. Access to SSH Keys Keepass database.
2. A computer with Microsoft Windows.
3. A full installation of PuTTY (i.e. not just the putty.exe executable).
4. A text editor that can save batch files (Notepad is fine).

Instructions

1. Copy J:\FullCount\Documentation\Office\Workstations\Authentication folder and contents under C:\Users\<user>\Documents to create template directories for the below steps.
2. Confirm that you have a full installation of PuTTY on your computer.
1. A full installation of PuTTY includes Pageant, PSFTP, PuTTY and PuTTYgen.
2. By default, the 64-bit version of these programs are installed in a folder named C:\Program Files\PuTTY.
3. If this directory does not exist on your computer, you probably do not have a full installation of PuTTY.
4. If you do not have a full installation of PuTTY, refer to the instructions in Install PuTTY SSH Client.
3. Save a copy of the encrypted SSH keys on your computer.

1. Checkout a copy of the SSH Keys KeePass database from Subversion.
2. Unlock the SSH Keys KeePass database.
3. Double-click on an entry to edit it.
4. Click on the Advanced tab.
5. Under Attachments, click on the name of the attachment (it should end in .ppk).
6. Click on the Save button, and choose a folder on your computer to save the SSH keys in. Make sure you put all of the SSH keys in the same folder.  Default location is C:\Users\<user>\Documents\Authentication\ssh keys
7. Repeat the last few steps for any other SSH keys you would like to use.
   **Note** This is a user-specific step - machines that are re-purposed for new hires will need this step taken again.

4. Create a batch file to launch Pageant.

1. Create a folder on your computer to save the batch file.  Our default location is C:\Users\<user>\Documents\Authentication\Pageant.
2. This will be prepopulated with a file called Pageant.bat if you copied contents from Step 1.
3. Right click on file and create a shortcut to be used in step 5.

5. Create a shortcut to automatically launch Pageant whenever you log into your computer.

1. Select Windows Key + R to open Run command window.  Enter shell:startup and select OK.
2. Copy Pageant - Shortcut.bat file from step 4. to startup folder.  Rename shortcut to Pageant.bat.
   **Note** This is a user-specific step - machines that are re-purposed for new hires will need this step taken again.

6. Test your shortcut and batch file.

1. Double-click on the shortcut. Pageant should a open new password dialog box for each SSH key listed in your batch file.

7. Set up your default profile in PuTTY.

1. Start PuTTY.
2. In the Category tree on the left, expand SSH, and then click on Auth.
3. Check the box next to Attempt authentication with Pageant.
4. Check the box next to Allow agent forwarding.
5. In the Category tree on the left, click on Session.
6. Under Saved Sessions, click on Default Settings.
7. Click on the Save button.

8. Set up a custom protocol handler for SSH.

1. This will allow you to start PuTTY by clicking on a link in your web browser.
2. Refer to the instructions in Launch PuTTY from Remote Connections Page.

Batch File Template

REM ---- Start of Batch File Template ----

@echo off

REM Path to pageant command.

set pageant="%ProgramFiles%\PuTTY\pageant.exe"

REM Path to the folder that contains your SSH keys.

set keystore="C:\Users\%USERNAME%\Documents\Authentication\SSH Keys"

REM Start pageant and load your SSH keys.

REM Empty double quotes seem to be required by the 'start' command.

start "" %pageant% %keystore%\production_ed25519.ppk

start "" %pageant% %keystore%\development_ed25519.ppk

start "" %pageant% %keystore%\test_ed25519.ppk

start "" %pageant% %keystore%\remote.ppk

start "" %pageant% %keystore%\terminals.ppk

start "" %pageant% %keystore%\terminals_ed25519.ppk

REM ---- End of Batch File Template ----

References

1. PuTTY User Manual
2. Using public keys for SSH authentication
3. Using Pageant for authentication