Merge pull request #131 from EPCCed/aaron-docs

MFA instructions for SSH Gateway

docs/access/ssh.md

@@ -16,6 +16,13 @@
 </style>
 
 The EIDF-Gateway is an SSH gateway suitable for accessing EIDF Services via a console or terminal. As the gateway cannot be 'landed' on, a user can only pass through it and so the destination (the VM IP) has to be known for the service to work. Users connect to their VM through the jump host using their given accounts.
+You will require three things to use the gateway:
+
+1. A user within a project allowed to access the gateway and a password set.
+1. An SSH-key linked to this account, used to authenticate against the gateway.
+1. Have MFA setup with your project account via SAFE.
+
+Steps to meet all of these requirements are explained below.
 
 ## Generating and Adding an SSH Key
 
@@ -55,6 +62,7 @@ If not, you'll need to generate an SSH-Key, to do this:
 1. Select the plus button under  'Credentials'
 1. Select 'Choose File' to upload the PUBLIC (.pub) ssh key generated in the last step, or open the <ssh-key>.pub file you just created and copy its contents into the text box.
 1. Click 'Upload Credential' - it should look something like this:
+
    ![eidf-portal-ssh](../images/access/eidf-portal-ssh.png){: class="border-img"}
 
 #### Adding a new SSH Key via SAFE
@@ -63,9 +71,29 @@ This should not be necessary for most users, so only follow this process if you
 If you need to add an SSH Key directly to SAFE, you can follow this [guide.](https://epcced.github.io/safe-docs/safe-for-users/#how-to-add-an-ssh-public-key-to-your-account)
 However, select your '[username]@EIDF' login account, not 'Archer2' as specified in that guide.
 
-### Using the SSH-Key to access EIDF - Windows and Linux
+## Enabling MFA via the Portal
+
+A multi-factor Time-Based One-Time Password is now required to access the SSH Gateway. <br>
+
+To enable this for your EIDF account:
+
+1. Login to the [portal.](https://portal.eidf.ac.uk)
+1. Select 'Projects' then 'Your Projects'
+1. Select the project containing the account you'd like to add MFA to.
+1. Under 'Your Accounts', select the account you would like to add MFA to.
+1. Select 'Set MFA Token'
+1. Within your chosen MFA application, scan the QR Code or enter the key and add the token.
+1. Enter the code displayed in the app into the 'Verification Code' box and select 'Set Token'
+1. You will be redirected to the User Account page and a green 'Added MFA Token' message will confirm the token has been added successfully.
+
+!!! note
+    TOTP is only required for the SSH Gateway, not to the VMs themselves, and not through the VDI.<br>
+    An MFA token will have to be set for each account you'd like to use to access the EIDF SSH Gateway.
+
+### Using the SSH-Key and TOTP Code to access EIDF - Windows and Linux
 
 1. From your local terminal, import the SSH Key you generated above: ```$ ssh-add [sshkey]```
+
 1. This should return "Identity added [Path to SSH Key]" if successful. You can then follow the steps below to access your VM.
 
 ## Accessing From MacOS/Linux
@@ -83,6 +111,8 @@ ssh -J [username]@eidf-gateway.epcc.ed.ac.uk [username]@[vm_ip]
 
 The `-J` flag is use to specify that we will access the second specified host by jumping through the first specified host.
 
+You will be prompted for a 'TOTP' code upon successful public key authentication to the gateway. At the TOTP prompt, enter the code displayed in your MFA Application.
+
 ## Accessing from Windows
 
 Windows will require the installation of OpenSSH-Server to use SSH. Putty or MobaXTerm can also be used but won’t be covered in this tutorial.
@@ -111,6 +141,8 @@ Windows will require the installation of OpenSSH-Server to use SSH. Putty or Mob
 ssh -J [username]@eidf-gateway.epcc.ed.ac.uk [username]@[vm_ip]
 ```
 
+You will be prompted for a 'TOTP' code upon successful public key authentication to the gateway. At the TOTP prompt, enter the code displayed in your MFA Application.
+
 ## First Password Setting and Password Resets
 
 Before logging in for the first time you have to reset the password using the web form in the EIDF Portal following the instructions in [Set or change the password for a user account](../services/virtualmachines/quickstart.md#set-or-change-the-password-for-a-user-account).