From 2b8e05e202d9664d807c6a71fbe4448dea8ecf33 Mon Sep 17 00:00:00 2001 From: awat31 Date: Tue, 19 Dec 2023 11:23:13 +0000 Subject: [PATCH 1/7] Updated docs for eidf-gateway when MFA is enabled --- docs/access/ssh.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index 122600288..efcdb7649 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -16,6 +16,13 @@ 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 @@ -63,7 +70,13 @@ 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 SAFE + +A multi-factor Time-Based One-Time Password is now required to access the SSH Gateway.
+To enable this for your EIDF account, follow the safe guide: [How to turn on MFA on your machine account](https://epcced.github.io/safe-docs/safe-for-users/#how-to-turn-on-mfa-on-your-machine-account) + + +### 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. @@ -83,6 +96,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 Applicaiton. + ## 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 +126,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 Applicaiton. + ## 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). From 8a45e92478c1347e1d51c820ef10873027a4cdde Mon Sep 17 00:00:00 2001 From: awat31 Date: Tue, 19 Dec 2023 11:31:53 +0000 Subject: [PATCH 2/7] Updated docs for eidf-gateway when MFA is enabled --- docs/access/ssh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index efcdb7649..71b04a846 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -19,7 +19,7 @@ The EIDF-Gateway is an SSH gateway suitable for accessing EIDF Services via a co 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. 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. From 15d1acfec9c7225e9e5edde5f61d7f651a77e0f0 Mon Sep 17 00:00:00 2001 From: awat31 Date: Tue, 19 Dec 2023 14:33:55 +0000 Subject: [PATCH 3/7] Format changes --- docs/access/ssh.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index 71b04a846..17f392233 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -62,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 .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 @@ -73,12 +74,13 @@ However, select your '[username]@EIDF' login account, not 'Archer2' as specified ## Enabling MFA via SAFE A multi-factor Time-Based One-Time Password is now required to access the SSH Gateway.
-To enable this for your EIDF account, follow the safe guide: [How to turn on MFA on your machine account](https://epcced.github.io/safe-docs/safe-for-users/#how-to-turn-on-mfa-on-your-machine-account) +To enable this for your EIDF account, follow the safe guide: [How to turn on MFA on your machine account](https://epcced.github.io/safe-docs/safe-for-users/#how-to-turn-on-mfa-on-your-machine-account) ### 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 @@ -126,7 +128,7 @@ 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 Applicaiton. +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 From 383109b9f1f33467d447111407428509f264c19a Mon Sep 17 00:00:00 2001 From: awat31 Date: Tue, 19 Dec 2023 14:37:49 +0000 Subject: [PATCH 4/7] Remove training whitespace --- docs/access/ssh.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index 17f392233..f34524c3a 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -16,11 +16,11 @@ 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: +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. +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. From f952ddcc3451842e7e0139cf18d6f6ce8baef65e Mon Sep 17 00:00:00 2001 From: awat31 Date: Fri, 12 Jan 2024 09:52:27 +0000 Subject: [PATCH 5/7] SSH Gateway MFA Changes --- docs/access/ssh.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index f34524c3a..cc9a6cdff 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -75,7 +75,20 @@ However, select your '[username]@EIDF' login account, not 'Archer2' as specified A multi-factor Time-Based One-Time Password is now required to access the SSH Gateway.
-To enable this for your EIDF account, follow the safe guide: [How to turn on MFA on your machine account](https://epcced.github.io/safe-docs/safe-for-users/#how-to-turn-on-mfa-on-your-machine-account) +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.
+ 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 From 8782ba6631f25252b9249459dc8cd81355025d30 Mon Sep 17 00:00:00 2001 From: awat31 Date: Fri, 12 Jan 2024 15:29:06 +0000 Subject: [PATCH 6/7] Updated header --- docs/access/ssh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index cc9a6cdff..3738ccee5 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -71,7 +71,7 @@ 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. -## Enabling MFA via SAFE +## Enabling MFA via the Portal A multi-factor Time-Based One-Time Password is now required to access the SSH Gateway.
From 1eace02f14b24b7b52a803a50c46916fa8f8667e Mon Sep 17 00:00:00 2001 From: awat31 Date: Fri, 12 Jan 2024 15:32:07 +0000 Subject: [PATCH 7/7] Spelling Correction --- docs/access/ssh.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/access/ssh.md b/docs/access/ssh.md index 3738ccee5..e6f955e87 100644 --- a/docs/access/ssh.md +++ b/docs/access/ssh.md @@ -111,7 +111,7 @@ 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 Applicaiton. +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