================================================== 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. .. sidebar:: Two-Factor Authentication Two-factor authentication (2FA) is a kind of multi-factor authentication. It is a method to confirm users' claimed identities by using a combination of two different factors: 1) something they know 2) something they have 3) or something they are. https://en.wikipedia.org/wiki/Multi-factor_authentication Index ----- - :ref:`req` - :ref:`configwinmac` - :ref:`cpwinmac` - :ref:`rsyncwinmac` - :ref:`win` - :ref:`app` .. _req: 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 .. _configwinmac: 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: .. code-block:: shell 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. .. _cpwinmac: Using SCP to copy files (Linux, MacOS) -------------------------------------- Several steps are needed to copy files. The following shows an example: .. code-block:: shell $ 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: .. code-block:: shell $ 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``: .. code-block:: shell $ 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: .. code-block:: shell $ 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. .. _rsyncwinmac: Using rsync (Linux, MacOS) -------------------------- The process for ``rsync`` is similar with just small differences. .. code-block:: shell $ 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: .. code-block:: shell $ 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: .. code-block:: shell [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: .. code-block:: shell $ rsync -prav -e 'ssh -o "SetEnv DUO_PASSCODE=sms"' -e 'ssh -o "SendEnv DUO_PASSCODE"' gro:sha256sums/ sums To then do: .. code-block:: shell $ 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: .. code-block:: shell # TODO .. _win: 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): .. code-block:: shell 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: .. code-block:: shell 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: .. code-block:: shell Host host.csr.uky.edu SendEnv DUO_PASSCODE User yourusername Save and close the file, then execute: .. code-block:: shell 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. .. code-block:: shell 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: .. code-block:: shell 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. .. _app: 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.