SSH: Duo Two-Factor Authentication (2FA)

This page is an extension of CS Guide's Secure Shell (SSH).

Duo 2FA is required for all SSH logins to Princeton University Computer Science research & computing servers. These include (aka portal, soak/wash/rinse/spin),,, and This implementation will use the Duo authentication from OIT (See Duo: Two-Factor Authentication - Get Started if you are not already enrolled).

If you are enrolled in OIT's Duo 2FA, there are no extra steps needed. The first factor will remain your CS password or publickey unless you are logging into or -- which authenticates with OIT credentials.

SSH protocol operations, such as sftp, scp and ssh itself, can trigger multiple Duo exchanges. Below you will find examples of SSH workflows and client setting customization.

A typical SSH workflow for non-2FA logins:

$ ssh
[$USER@spin ~]$

Either pubkey or password authentication method is applied and $USER is logged in.

A Typical SSH Workflow for 2FA logins:

$ ssh
Duo two-factor login for $user Enter a passcode or select one of the following options: 
1. Duo Push to XXX-XXX-1234
2. Phone call to XXX-XXX-1234
3. SMS passcodes to XXX-XXX-1234 (next code starts with: 2)

Passcode or option (1-3):

Either pubkey or password authentication method is applied and then a Duo authentication prompt appears with options.

Linux/MAC users:

To make the user experience more convenient and efficient, users can modify their SSH client settings to create multiplexed connections that will prevent having to authenticate with Duo each time to the same remote host.

To customize your SSH client settings, find your .ssh folder, typically found at ~/.ssh. Inside this folder, if not present, create a file called 'config'. Set file permissions: `chmod 600 config`. Inside config is where you will set specifics for each host you access.


Host *
    ControlPath ~/.ssh/controlsocket/%C
    ControlMaster auto

Host portal

After creating the file, save and exit. Then `mkdir ~/.ssh/controlsocket` and `chmod 700 ~/.ssh/controlsocket` . This will create the directory where each multiplexed SSH socket is written.

At this point you will `ssh portal` and any subsequent ssh sessions from the same source host will use the ~/.ssh/controlsocket/%C file.

Course Accounts:

Can be accessed by logging in to your personal CS netID first, then, from there logging into the desired account. This nested approach may not be fully convenient for those who make use of SCP, SFTP; in these cases, using the ProxyJump option may be more efficient. See below for links to more advanced documentation.

More customization info can be found here:

Microsoft Windows users:

Most Microsoft Windows users who interact with SSH protocol operations typically utilize a GUI application, e.g., PuTTY, SecureCRT, Filezilla, etc. Windows 10 users may find WSL2 as a good solution for setting up and using its SSH server.


PuTTY will work normally with password and pubkey authentication as a first factor.



Instructions for setting up an interactive site connection using "Site Manager":

  • File --> Site Manager
  • Create New Site --> Fill out General Tab Settings --> Protocol,Host,Port,Logon:Interactive,User
  • Connect --> Password
  • Enter Duo Prompt option --> SUCCESS!

WSL2 (Windows Subsystem for Linux 2):

Requirement: Windows 10