Computer Science Two Factor Authentication for SSH¶
When required, CS uses Two Factor Authentication (2FA) for ssh logins in order to add a layer of security to the user-authentication process. You can use your linkblue Campus username to authenticate on hosts that are 2FA enabled, but you have to provide a second factor after a successful ssh login.
Note
This page documents parts of 2FA that need additional setup from users. The following sections describe how to use ssh and related programs when 2FA is required. The 2FA process changes the way in which we normally interact with the ssh server.
Index¶
Requirements¶
First, you need to enroll your device in the UK Campus 2FA infrastructure. If you haven’t done so, please follow the instructions documented in the following link: https://uky.service-now.com/techhelp?id=kb_article&sysparm_article=KB0012096&sys_kb_id=d5dead9bdb270c14ae2f5c68dc9619c0
2FA with non-interactive login setup (Linux and MacOS)¶
We have tested these instructions with MacOS and Linux; they should work
for any Unix-like operating system that uses the OpenSSH project’s tools.
Whenever you login from a client machine to a host with 2FA enabled via ssh(1) to execute commands (we call that an interactive login) everything just works after you complete the 2FA steps. However, when with 2FA enabled whenever you attempt to copy files with scp(1), rsync(1), or sftp(1), the default settings do not work, because these connections are not interactive. The following sections provide some solutions for the most commonly used tools.
The ~/.ssh/config file (Linux, MacOS)¶
On your client machine, you need to modify (or create) ~/.ssh/config with
something like the following example:
Host delta.csr.uky.edu
SendEnv DUO_PASSCODE
User yourusername
In this example, you might want to copy files from delta.csr.uky.edu, a
2FA-enabled ssh server. To be able to do so, you need to set the server name
for which the settings apply (adjust it based on the ssh server that you plan to
use) and make sure you add the SendEnv option. You will see in the next
section the usefulness of this configuration.
Using SCP to copy files (Linux, MacOS)¶
Several steps are needed to copy files. The following shows an example:
$ env DUO_PASSCODE=sms scp -r user@delta.csr.uky.edu:myfiles/ cs_files/
This command first sets the DUO_PASSCODE environment variable and then calls
scp. In the previous step we configured the ~/.ssh/config file to send
this variable to the delta.csr.uky.edu ssh server. This call to scp
requests a passcode and then fails. You will then receive a temporary passcode
on your device. Say, for example, the passcode is 1354475. Then:
$ env DUO_PASSCODE=1354475 scp -r user@delta.csr.uky.edu:myfiles/ cs_files/
cs322.txt 100% 6 525.4KB/s 00:00
cs322_homework.txt 100% 6 932.4KB/s 00:00
This command tries again, but this time assigning the received passcode to the DUO_PASSCODE environment variable, and it succeeds.
Your ssh configuration specifies that programs based on ssh should send that variable’s value to the ssh server, which then completes the 2fA authentication process.
Another variant of the command is to not configure ~/.ssh/config, but
instead pass the SendEnv option to scp:
$ export DUO_PASSCODE=sms
$ scp -o 'SendEnv DUO_PASSCODE' user@delta.csr.uky.edu:skills.txt .
This version explicitly sets the SendEnv option.
You could place DUO_PASSCODE=sms in your shell’s initialization file.
Then you don’t need to set it anymore as the first step. In that case, sms
is its value, and you should receive an sms message with the passcode.
As in the previous example, the first command will fail, but it will cause 2FA
to generating a passcode and send it to your device. You use this passcode to
repeat the command replacing sms by your numeric passcode on your
environment variable and then executing the command:
$ export DUO_PASSCODE=1234567
$ scp -o 'SendEnv DUO_PASSCODE' user@delta.csr.uky.edu:skills.txt .
Note
Replace 1234567 with your passcode.
Note
Note that you will be required to use your password first before any operation can be initiated.
Using rsync (Linux, MacOS)¶
The process for rsync is similar with just small differences.
$ export DUO_PASSCODE=sms
$ rsync -e 'ssh -o "SendEnv DUO_PASSCODE"' user@delta.csr.uky.edu:file.txt .
Once you receive the passcode, do the following:
$ export DUO_PASSCODE=123456;
$ rsync -e 'ssh -o "SendEnv DUO_PASSCODE"' user@delta.csr.uky.edu:file.txt .
replacing 123456 with your passcode.
The following is a full example session that copies a directory using rsync when 2fA is enabled:
[4583]$ export DUO_PASSCODE=sms
[4584]$ rsync -prav -e 'ssh -o "SendEnv DUO_PASSCODE"' user@delta.csr.uky.edu:sha256sums/ .
rsync: connection unexpectedly closed (0 bytes received so far) [Receiver]
rsync error: error in rsync protocol data stream (code 12) at io.c(235) [Receiver=3.1.2]
[4585]$ export DUO_PASSCODE=1470231
[4586]$ rsync -prav -e 'ssh -o "SendEnv DUO_PASSCODE"' user@delta.csr.uky.edu:sha256sums/ sums/
receiving incremental file list
./
sha256sum.txt
bsd-sha256sums.txt
You can also combine exporting DUO_PASSCODE and the rsync command in one line:
$ rsync -prav -e 'ssh -o "SetEnv DUO_PASSCODE=sms"' -e 'ssh -o "SendEnv DUO_PASSCODE"' gro:sha256sums/ sums
To then do:
$ rsync -prav -e 'ssh -o "SetEnv DUO_PASSCODE=123456"' -e 'ssh -o "SendEnv DUO_PASSCODE"' gro:sha256sums/ sums
This process leads to a shell script to automate the process:
# TODO
Copying Files with Windows¶
This section documents how to copy files or directories from Windows clients using the scp command-line program.
Requirements¶
if you are using a Windows 10 build that includes the OpenSSH binaries (ssh, scp, etc.) then proceed to the next sub-section. Otherwise, install the binaries following these instructions https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse . For the purposes of this document just use the content of the section titled Installing OpenSSH with PowerShell.
If the previous PowerShell instructions don’t work, you might have an old build of Windows. In that case, you can download the OpenSSH binaries manually from this link: https://github.com/PowerShell/Win32-OpenSSH/releases which belongs to Microsoft’s OpenSSH Github repository.
Note
The location of the .ssh\config file on Windows is in the user’s profile directory. For example if your username is myname, your profile should be in C:\Users\myname\ , and therefore ssh config files are in the .ssh\ directory located in your profile directory.
For the purposes of this document, it doesn’t matter which package you install or if you downloaded the standalone binaries. Just make sure you can use the ssh and scp commands. The command parameters are the same as in Unix, and the file configuration (config) is also in the same format (it’s the same software) and in the same location (the .ssh directory)
If you downloaded the standalone binaries, you will have to open a command line
window (Windows + R or click on the start menu and type cmd) and change
the current directory (using cd) to the one where you downloaded/copied the
OpenSSH standalone binaries, which could be something like this (depending on
where you copied them):
cd C:\Users\myname\Downloads\OpenSSH-Win64\OpenSSH-Win64
Once you are in that directory you can directly use the ssh and scp commands.
Configuring the PATH environment variable¶
This section is optional, but if you don’t want to change to a directory every time you want to copy files remotely, then another option is to modify your %PATH% environment variable and append the location where you installed the standalone tools.
Then you just need to execute the command interpreter and directly execute ssh or scp.
Open Windows Explorer, right click on My Computer, select Properties, select Advanced System Configuration and then select Environment Variables.
Once there, the upper panel represents your user-defined variables. You can modify PATH by selecting Edit. At the end of the text field (after a semicolon) add the path where you installed the openssh tools. You can now launch a command line interpreter and use ssh or scp without changing to a different path.
Creating .ssh\config¶
You need do set this up only once. Open a command line and execute:
mkdir %USERPROFILE%\.ssh
notepad %USERPROFILE%\.ssh\config
Add the server name(s) to the configuration file and add the DUO_PASSCODE
environment variable as a parameter to the SendEnv option:
Host host.csr.uky.edu
SendEnv DUO_PASSCODE
User yourusername
Save and close the file, then execute:
move %USERPROFILE%\.ssh\config.txt %USERPROFILE%\.ssh\config
Copying files with scp¶
The command line is the same as in the Linux examples above. To copy files or directories, use the command scp. See the following example.
Note
With -v enabled, you will see debugging information, but it’s not needed for this to work.
scp -v -o "SetEnv DUO_PASSCODE=sms" -o "SendEnv DUO_PASSCODE" md5.cs.uky.edu:file.txt .
Executing: program ssh.exe host md5.cs.uky.edu, user cs, command scp -v -f file.txt
OpenSSH_for_Windows_8.1p1, LibreSSL 2.9.2
debug1: Reading configuration data C:\users\cs/.ssh/config
debug1: C\Users\cs\.ssh\config line 1: Applying options for md5.cs.uky.edu
...
debug1: Connection established.
...
debug1: Sending env DUO_PASSCODE = sms
...
The first attempt will fail, but you will receive a passcode on your device. Use it to set the environment variable, as in the following example:
scp -v -o "SetEnv DUO_PASSCODE=123456" -o "SendEnv DUO_PASSCODE" md5.cs.uky.edu:file.txt .
Where 123456 is the passcode received.
Note
This example can even be used when no ssh/config file was created since it first sets and then
send DUO_PASSCODE on just one command line.
Appendix A: Possible values for DUO_PASSCODE¶
Possible values that could be assigned to DUO_PASSCODE when initiating the
2fA process are:
sms,push,phone, or just use a passcode if you already have one.
Select the one that works best for you.