Before you begin Set up SSH public key authentication on a Linux or macOS computer Set up public key authentication
- using PuTTY on a Windows 11, Windows 10, or Windows 8.x computer
- Before you begin
public key authentication to connect to a
remote system is a robust and more secure alternative to logging in with an account password or passphrase. SSH public key authentication is based on asymmetric cryptographic algorithms that generate a separate key pair (a key pair), one “private” and the other “public”. Keep the private key secret and store it on the computer that you use to connect to the remote system. Possibly, you can share the public key with anyone without compromising the private key; Store it on the remote system in an .ssh/authorized_keys directory.
To use public key authentication
- The remote system must have an SSH version installed. The information in this document assumes that the remote system uses OpenSSH. If the remote system is using a different version of SSH (for example, Tectia SSH), the process described below may not be successful.
- The computer you use to connect to the remote server must have an SSH version installed. This document includes instructions for generating a key pair with command-line SSH on a Linux or macOS computer, and with PuTTY on a Windows computer.
- You must be able to transfer your public key to the remote system. Therefore, you must be able to log on to the remote system with an account username and password/passphrase set, or have a remote system administrator add the public key to your account’s ~/.ssh/authorized_keys file.
- two-step login (Duo) is required to access login nodes on UI research supercomputers and for SCP and SFTP file transfers to those systems. SSH public key authentication remains an option for researchers who send the “SSH Public Key Authentication to HPS Systems” agreement (log in to HPC everywhere with your username and UI passphrase), in which you agree to set a passphrase on your private key when you generate your key pair. If you have questions about how two-factor authentication can affect your workflows, contact the UITS Research and Deep Learning Applications team. For help, see Introduction to two-step sign-in (Duo) in UI and Two-step sign-in help (Duo).
Two-factor authentication via
Configure SSH public key authentication on a Linux or macOS computer
To configure SSH public key authentication
Linux or macOS
- Log on to the computer that you will use to access the remote host, and then use command-line SSH to generate a key pair using the RSA algorithm.
To generate RSA keys, at the command line, type: ssh-keygen
- password (to protect your private key): File name: To accept the default file name
- (and location) for the key pair, press Enter or Return without entering a file name.
Alternatively, you can type a file name (for example, my_ssh_key) at the command prompt, and then press Enter or Return. However, many remote hosts are configured to accept private keys with the default file name and path (~/.ssh/id_rsa for RSA keys) by default. Consequently, to authenticate with a private key that has a different file name or one that is not stored in the default location, you must explicitly invoke it on the SSH command line or in an SSH client configuration file (~/.ssh/config); See below for instructions.
- Password: Type a password that contains at least five characters, and then press Enter or Return. If you press Enter or Return without entering a password, your private key will be generated without password protection.
Your private key will be generated using the default file name (e.g. id_rsa) or filename you specified (e.g. my_ssh_key) and stored on your computer in an .ssh directory outside your home directory (e.g. ~/.ssh/
id_rsa or ~/.ssh/my_ssh_key). The corresponding public key will be generated using
file name (but with a .pub extension appended) and stored in the same location (for example, ~/.ssh/id_rsa.pub or ~/.ssh/my_ssh_key.pub).
- (and location) for the key pair, press Enter or Return without entering a file name.
- ) to your account on the remote system (for example, firstname.lastname@example.org); for example, using command-line SCP: scp ~/.ssh/id_rsa.pub email@example.com:
You will be prompted for your account password. Your public key will be copied to your home directory (and saved under the same file name) on the remote system.
- with your account username and password
- type the following commands: mkdir -p
- , add the contents of the public key file (for example, ~/id_rsa.pub) to a new line in the ~/.ssh/authorized_keys file;
- Type: rm ~/id_rsa.pub
Alternatively, if you prefer to keep a copy of your public key on the remote system, move it to your .ssh directory; on the command line, type:
mv ~/id_rsa.pub ~/.ssh/
- Optionally, repeat steps 3 through 7 to add
- You should now be able to SSH to your account on the remote system (e.g. firstname.lastname@example.org) from the computer (e.g. host1) that has your private key (for example, ~/.ssh/id_rsa): If your private key is password protected, the remote system
- will ask you for the password or passphrase (your private key password/passphrase is not transmitted to the remote system): [username@host1 ~]$ ssh email@example.com Enter the passphrase for the key ‘/username/Host1/.ssh/id_rsa’:
- is not password protected, the remote system will place it on the command line in your home directory without asking for a password or passphrase: [username@host1~]$ ssh firstname.lastname@example.org Last login: Mon Oct 20 09:23:17 2014 from host1.somewhere_else.edu If the private key
Last login: Mon Oct 20 09:23:17 2014 from host1.somewhere_else.edu If your private key
that you are using does not have the default name or is not stored in the default path (not ~/.ssh/id_rsa), you must explicitly invoke it in one of two ways
- On the SSH command line: Add the -i flag and path to your private key. For example, to invoke the host2_key private key, stored in the ~/.ssh/old_keys
directory, when connecting to your account on a remote host (for example, email@example.com), type
: ssh -i ~/.ssh/old_keys/host2_key firstname.lastname@example.org
- In an SSH client configuration file: SSH obtains configuration data from the following sources (in this order): From command-line options From the user’s client configuration file (~/.ssh/
- config), if existing
- etc/ssh/ssh_config) The
client configuration file (/
SSH client configuration file is a text file that contains keywords and arguments. To specify which private key to use for connections to a particular remote host, use a text editor to create a ~/.ssh/config that includes the Host and IdentityFile keywords.
For example, for connections to host2.somewhere.edu, to have SSH automatically invoke the host2_key private key, stored in the ~/.ssh/old_keys directory, create a ~/.ssh/config file with these lines included:
Host host2.somewhere.edu IdentityFile ~/.ssh/old_keys/host2_key
Once you save the file, SSH will use the specified private key for future connections to that
You can add multiple Host and IdentityFile policies to specify a different private key for each host listed; for example:
Host host2.somewhere.edu IdentityFile ~/.ssh/old_keys/host2_key Host host4.somewhere.edu IdentityFile ~/.ssh/old_keys/host4_key Host host6.somewhere.edu IdentityFile ~/.ssh/old_keys/host6_key
Alternatively, you can use a single asterisk ( * ) to provide global defaults for all hosts (specify a private key for multiple hosts); for example:
Host *.somewhere.edu IdentityFile ~/.ssh/old_keys/all_hosts_key For more information about the SSH client configuration file
, see the OpenSSH SSH client configuration file on the web or from the command line (man ssh_config).
You will be asked to provide a file name (to save the key pair) and a
Use SFTP or SCP to copy the public key file (for example, ~/.ssh/id_rsa.pub
Log in to the remote system
. If your account on the remote system does not already contain a ~/.ssh/authorized_keys file, create one; At the command line,
~/.ssh touch ~/.ssh/authorized_keys On the remote system
At the command line, type: cat ~/id_rsa.pub >> ~/.ssh/authorized_keys You may want to check the contents of ~/.ssh/authorized_keys to make sure your public key was added correctly; At the command line, type: more ~/.ssh/authorized_keys You can now safely delete the public key file (for example, ~/id_rsa.pub) from your account on the remote system; at the command line,
the public key to other remote systems that you want to access from the computer that has your private key using SSH public key authentication.
Set up public key authentication using PuTTY on a Windows
11, Windows 10, or Windows 8.x
computer The PuTTY command-line SSH client,
PuTTYgen key generation utility, Pageant SSH authentication broker, and PuTTY SCP and SFTP utilities are packaged together in a Windows installer available under the MIT license for free download from the PuTTY development team. After installing PuTTY:
- Start PuTTYgen
- In the “PuTTY Key Generator” window, under “Parameters”: For
- “Type of key to generate”, select RSA. (In earlier versions of PuTTYgen, select SSH2-RSA.)
- For “Number of bits in a generated key”, leave the default value (2048).
- Actions”, click Generate
- prompted, use the mouse (or trackpad) to move the cursor around the blank area below “Key”; this generates randomness that PuTTYgen uses to generate its key pair. When the key pair is generated, PuTTYgen
- displays the public key in the area under “Key”. In the “Key passphrase” and “Confirm passphrase” text boxes, type a passphrase to protect your private key with a passphrase.
- public key.
- Name the file (for example, putty_key), select a location on your computer to store it, and then click Save
. Save your private key: Under
- private key
- Save as type” set to PuTTY Private Key Files (*.ppk), name the file (for example, putty_private_key), select a location on your computer to store it, and then click Save.
- If you want to connect to a remote desktop system such as Research Desktop (RED), click Conversions > Export OpenSSH Key, name the file (for example, putty_rsa), select a location on your computer to store it, and then click Save.
. Keep “
- Log in to the remote system with your account username and password. If your
remote system does not support password-based authentication, you will need to ask system administrators to add your public key to your account’s ~/.ssh/authorized_keys file (if your account does not have the ~/.ssh/authorized_keys file, system administrators can create one for you). Once your public key is added to your account’s ~/.ssh/authorized_keys file on the remote system…
- create one; at the command line, type the following commands: mkdir -p ~/.ssh touch ~/.ssh/authorized_keys
If your account on the remote system already has ~/.ssh/authorized_keys, running these commands will not damage the existing directory or file.
- On your computer, in the PuTTYgen utility, copy the contents of the public key (shown in the area under “Key”) to your Clipboard. Then, on the remote system, use your favorite text editor to paste it on a new line into your ~/.ssh/authorized_keys file, and then save and close the file.
- On your computer, open the Pageant SSH authentication broker. This utility runs in the background, so when it opens, you should see its icon in the Windows notification area.
- In the Windows notification area, right-click the Parade icon, select Add Key, navigate to the location where you saved the private key (for example, putty_private_key.ppk), select the file, and then click Open.
- , and then click OK. If your private key
is not protected by passphrase
, Pageant will add your private key without asking for a passphrase.
Either way, Pageant stores the unencrypted private key in memory for PuTTY to use when you start an SSH session on the remote system that has your public key.
- or IP address)”, enter your username along with the hostname of the remote server that has your public key; for example: email@example.com
- Connection Type”, make sure SSH is selected. In
- Category” list on the left, navigate to the authentication screen (Connecting > SSH > Auth). On the Authentication screen, under “Authentication methods”, select Try authentication using Pageant.
- “Saved Sessions”, type a name (for example, Death Star), and then click Save
- Click Open to connect to your account on the remote system. With Pageant running in the background, PuTTY will automatically retrieve the unencrypted private key from Pageant and use it to authenticate. Because Pageant has your private key password saved (if applicable), the remote system will place it on your account’s command line without prompting you for the passphrase.
Return to the Session screen, and in
- Open the Startup folder. Press Win-r, and in the “Open” field, type shell:startup, and then press Enter.
- Right-click inside the Startup folder, and then select New and Shortcut.
- Pageant executable (pageant.exe) followed by the path to the private key file (for example, putty_private_key.ppk); enclose both paths in double quotation marks; for example: “C:\Program Files (x86)\PuTTY\pageant.exe” “C:\Users\user_profile\ssh_key\putty_private.ppk”
- Click Next, and then in the “Type a name for this shortcut” text box, type a name for the shortcut (for example, PAGEANT).
- Click Finish.
Save your public key: Under “Actions”, next to “Save generated key”, click Save
“Actions”, next to “Save generated key”, click Save
If your account on the remote system does not already contain a ~/.ssh/authorized_keys file,
If your private key is protected by passphrase, Pageant will ask you to enter the passphrase; type the passphrase for your private key
On your computer, open the PuTTY SSH client: On the Session screen: Under “Hostname (
In the “Enter the location of the item” text box, type the path to the
The next time you log in to your Windows desktop, Pageant will automatically launch, upload your private key, and (if applicable) ask for your passphrase.