SSH Key Authentication - Client configuration

This article provides instructions for configuring remote login to web hosting user accounts via SSH using SSH Key Authentication rather than a password. If you're not sure why this is important, you can read our article on Securing Remote access via SSH and Server Security.

Generating a key pair

First, you need to generate a public and private key pair for each computer that connects to a particular user account on the dedicated server.

Windows

You'll need the following programs for this: Putty, Puttygen, Pageant. They can be downloaded from the Putty website. Feel free to save them anywhere on your machine; the following instructions will assume you have saved them to your desktop.

To generate the keys:

  1. Run Puttygen, and under Parameters change Number of bits in a generated key to '2048'. Leave Type of key to generate as 'SSH-2 RSA'.

  2. Click on Generate, and move the mouse over the bar at the top until it fills.
  3. Once the keys are generated, change the Key comment field to 'USERNAME@SERVERNAME', replacing these with the details of the account you will be using the key with.

  4. Choose a password, and type it into into the Key passphrase and Confirm passphrase fields. The same caution should be taken with this passphrase as with any other password you use.

  5. Save both the public and private keys. They should have the same filename before the extension. Save these to a location that is not shared with anyone else. In the interest of making it easy for future steps, saving it to a location like C:\keys\ is a good idea.

  6. Notice the Public key for pasting... section. You'll need to copy and paste it onto the server in the next step.

OS X

OS X comes with the terminal-based OpenSSH client already installed, however there is a handy GUI based utility for managing your SSH keys that integrates with this, called SSHKeychain. Download this and install as per the instructions on the website, then run it. You may also wish to download and install iTerm rather than use the standard Terminal application that comes with OS X.

  1. Click on the keyring icon that appears on the right hand side of the menu bar and select "Preferences" from the menu.
  2. Click on "SSH Keys".
  3. Click "New".
  4. Click "Select" and select a filename for the key (this can be anything). Leave the location as the default.
  5. Select "RSA" from the "Type" box and "2048" from the "Nr. of bits" box.
  6. Enter a passphrase. The same caution should be taken with this passphrase as with a normal password.
  7. Click "Generate".
  8. Click on the "Environment" icon and tick "Manage". Logout of OS X and log back in.
  9. Open up a terminal (or iTerm) window and type the command cat .ssh/KEYNAME.pub . You'll need to copy and paste it onto the server in the next step.

Server configuration

You will now need to place your public key on the shared web hosting or dedicated server you wish to authenticate with:

  1. SSH in through your SSH client (e.g. Putty) with a password.
  2. mkdir .ssh if it does not exist.

  3. chmod 700 .ssh

  4. vi .ssh/authorized_keys and hit 'i' to enter insert mode.

  5. Cut and paste the public key you generated in the previous step into your SSH terminal. Make sure it comes out as a single, wrapped line, and be careful of missing characters or extra line breaks.
  6. Hit 'Esc', then ':'.
  7. Type 'wq' and hit 'Enter'. This should exit vi.
  8. chmod 600 .ssh/authorized_keys2

  9. Log out of your SSH session.

Using the new key

Windows

On your machine:

  1. Open Pageant, then right-click on the icon in the system tray and select 'Add Key'.
  2. Browse to where your private key was saved and double-click on it.
  3. Enter in your passphrase. If correct, the window will close and your key will be saved.
  4. Open Putty, and select SSH->Auth from the left hand menu. Make sure Attempt authentication using Pageant is ticked.

  5. Connect as you normally would.

You should immediately get an SSH session without a password. If this has worked, then you'll next want to automate the keys loading when Pageant starts.

On your machine:

  1. Right-click on your desktop and select New, and then Shortcut.
  2. Click on Browse and locate your pageant.exe file where it was saved and double-click on it.
  3. It will now have the full path ie, "C:\Documents and Settings\USERNAME\Desktop\pageant.exe" in quotes. Click on this field and scroll to the end.

  4. You will now need to enter the path to your key in quotes. This is where a shorter path makes it easier. Note that the quotes are required for this. The field should look something like this when complete: C:\Documents and Settings\USERNAME\Desktop\pageant.exe C:\keys\YOURKEY.ppk

  5. Click on Next and type in a name for the shortcut. Something descriptive like "My SSH Keys" will help avoid confusion if you'd saved Pageant to your desktop.

Double-clicking on your shortcut should prompt you for your passphrase. After typing that in, all future sessions (as long as Pageant is open) will log you in without prompting for anything.

OS X

  1. Open the SSH Keychain application.
  2. Click on the keyring in the menubar and select: Agent -> Add Single Key

  3. Select your key and click Open. You should be prompted for the key passphrase.

Now you simply need to use SSH to connect to a server as normal. SSHKeychain should let you log in automatically.


See also: