|
| 1 | +[](){#mfa} |
| 2 | +# Multi Factor Authentification |
| 3 | + |
| 4 | +!!! todo |
| 5 | + These docs have been mostly cut and paste, with some small changes. |
| 6 | + |
| 7 | + I did some refactoring to make them a bit easier to read, and more logical for linking to other docs. |
| 8 | + |
| 9 | + But they should be more user friendly, because they will often be the first docs that users interact with as they acccess CSCS. |
| 10 | + |
| 11 | +To access CSCS services and systems users are required to authenticate using multi-factor authentication (MFA). |
| 12 | +MFA is implemented as a two-factor authentication, where one factor is the login and password pair ("the thing you know") and the other factor is the device which generates one-time passwords (OTPs, "the thing you have"). |
| 13 | +In this way security is significantly improved compared to single-factor (password only) authentication. |
| 14 | + |
| 15 | +The MFA workflow uses a time-based one-time password (OTP) to verify identity. |
| 16 | +An OTP is a six-digit number which changes every 30 seconds. |
| 17 | +OTPs are generated using a tool installed on a device other than the one used to access CSCS services and infrastructure. |
| 18 | +We recommend to use a smartphone with an application such as Google Authenticator to obtain the OTPs. |
| 19 | + |
| 20 | +<div class="grid cards" markdown> |
| 21 | + |
| 22 | +- :fontawesome-solid-headset: [__Getting Started__][mfa-setup] |
| 23 | + |
| 24 | + Get the authenticator app set up on your phone. |
| 25 | + |
| 26 | +- :fontawesome-regular-comments: [__Log in to a cluster__][mfa-ssh] |
| 27 | + |
| 28 | + Use SSH to log into a cluster. |
| 29 | + |
| 30 | +- :fontawesome-regular-comments: [__Access a CSCS web app__][mfa-web] |
| 31 | + |
| 32 | + MFA is required to log into CSCS web services. |
| 33 | + |
| 34 | +</div> |
| 35 | + |
| 36 | +[](){#mfa-setup} |
| 37 | +## Getting Started |
| 38 | + |
| 39 | +When you first log in to any of the CSCS web applications such as UMP, Jupyter, etc., you will be asked to register your device. |
| 40 | + |
| 41 | +Firstly, you will be asked to provide a code that you received by email. |
| 42 | +After this validation step, you will need to scan a QR code with your mobile phone using an application such as Google Authenticator. |
| 43 | +Lastly, you will need to enter the OTP from the authenticator application to complete the registration of your device. |
| 44 | +From then on, two-factor authrentication will be required to access CSCS services and systems. |
| 45 | +A more detailed explanation of the registration process is provided in the next section. |
| 46 | + |
| 47 | +!!! warning |
| 48 | + It is not possible to log in to CSCS systems using SSH without registering a device and creating certified SSH keys. |
| 49 | + See below for details on generating certified SSH keys. |
| 50 | + |
| 51 | +### Authenticator Application |
| 52 | + |
| 53 | +CSCS supports authenticators that follow an open standard called [TOTP](https://en.wikipedia.org/wiki/Time-based_one-time_password). |
| 54 | +The recommended way to access such an authenticator is to install an application on your mobile phone. |
| 55 | +Google Authenticator and FreeOTP have been tested successfully; however, if you are using a different mobile application for OTPs, feel free to continue using it - given it supports the TOTP standard. |
| 56 | + |
| 57 | +You can download Google Authenticator for your phone: |
| 58 | + |
| 59 | +* :fontawesome-brands-android: Android: on the [Google Play Store](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2). |
| 60 | +* :fontawesome-brands-apple: iOS: on the [Apple Store](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2). |
| 61 | + |
| 62 | +[](){#configure-otp} |
| 63 | +### Configure the Authenticator |
| 64 | + |
| 65 | +Before starting, ensure that the following pre-requisites are satisfied |
| 66 | + |
| 67 | +1. You have an invitation email from CSCS for MFA enrollment |
| 68 | + * a notification email will be sent atleast one week before we sent the invitation email. |
| 69 | +2. You have installed an OTP Authenticator app on your mobile device (see above). |
| 70 | + |
| 71 | +!!! note |
| 72 | + If you try access any of our web applications without setting up MFA, you will be redirected to enroll for MFA. |
| 73 | + |
| 74 | +!!! warning |
| 75 | + If you try to SSH to CSCS systems without setting up MFA, you will be prompted with permission denied error, for example: |
| 76 | + ``` |
| 77 | + > ssh ela.cscs.ch |
| 78 | + [email protected]: Permission denied (publickey). |
| 79 | + Connection closed by UNKNOWN port 65535 |
| 80 | + ``` |
| 81 | + |
| 82 | +Steps: |
| 83 | + |
| 84 | +1. Access any of the CSCS Web applications such as [`account.cscs.ch`](https://account.cscs.ch), Jupyter, etc., on a new browser session which will redirects you to the CSCS login page. |
| 85 | +2. Log in with your username and password. |
| 86 | +3. You will be asked to key in a code which CSCS Authentication system sent to you by email. |
| 87 | + After successfaul validation of the code you will be redirected to the next page which present a QR code. |
| 88 | +4. Scan the QR code with the authenticator app that was installed on your mobile device. |
| 89 | + After scanning the QR code the authenticator app will start generating a new 6 digit OTP every 60 seconds. |
| 90 | +5. To complete the OTP registration process, please enter the 6 digit OTP from the authenticator app at the bottom of the the same QR code page. Optionally, you can input your device name where you imported the OTP seed by scanning the QR code |
| 91 | +6. On successful registration you will be logged into the CSCS web application that you accessed in step-1 |
| 92 | + |
| 93 | +!!! todo |
| 94 | + do we need the images from KB? |
| 95 | + |
| 96 | +### Resetting the Authenticator |
| 97 | + |
| 98 | +In case users lose access to their mobile device/Authenticator OTP, users can reset their OTP by following the below self-service process. |
| 99 | + |
| 100 | +1. Access any CSCS web application like: [account.cscs.ch](https://account.cscs.ch/) which redirects you to the CSCS Login page. |
| 101 | +2. From the login screen, click the "Reset OTP" link below the "LOG IN" button |
| 102 | +3. Enter your username and password. |
| 103 | +4. On successful validation of user credentials, users will receive an email with a reset credentials link like the one below, click on the link in the email |
| 104 | +5. The steps are the same as for the first time you [configured the authenticator][configure-otp]. |
| 105 | + |
| 106 | +!!! warning |
| 107 | + When replacing your smartphone remember to sync the authenticator app before resetting the old smartphone. |
| 108 | + Otherwise, you will have to follow this process. |
| 109 | + |
| 110 | +[](){#mfa-web} |
| 111 | +## Using MFA to acccess web-based services |
| 112 | + |
| 113 | +After having completed the setup of your authenticator, you will be asked to enter your login/password and the OTP to access all web-based services. |
| 114 | + |
| 115 | +1. Enter username and password. |
| 116 | + * if the wrong username / password combination is entered, you will see an error. |
| 117 | +  |
| 118 | +2. Then you will be prompted to enter the 6-digit code obtained from your device. |
| 119 | +  |
| 120 | + |
| 121 | +[](){#mfa-ssh} |
| 122 | +## Using MFA with SSH |
| 123 | + |
| 124 | +It is not possible to authenticate with a username/password and user-created SSH keys: it is necessary to use a certified SSH key created by a CSCS SSHService. |
| 125 | + |
| 126 | +!!! note |
| 127 | + Keys are valid for 24 hours, after which a new key must be generated. |
| 128 | + |
| 129 | +!!! warning |
| 130 | + The number of certified SSH keys is limited to **five per day**. |
| 131 | + Once you have reached this number you will not be able to generate new keys until at least one of these key expires or keys are revoked. |
| 132 | + |
| 133 | +### Step 1: generate SSH keys |
| 134 | + |
| 135 | +There are two methods for generating SSH keys using the SSHService, the [SSHService web app](https://sshservice.cscs.ch/) or by using a [command-line script](https://github.com/eth-cscs/sshservice-cli). |
| 136 | + |
| 137 | +#### Getting keys via the command line |
| 138 | + |
| 139 | +On Linux and MacOS, the SSH keys can be generated and automatically installed using a command-line script. |
| 140 | +This script is provided in pure Bash and in Python. |
| 141 | +Python 3 is required together with packages listed in `requirements.txt` provided with the scripts. |
| 142 | + |
| 143 | +!!! note |
| 144 | + We recommend to using a [virtual environment](https://user.cscs.ch/tools/interactive/python/#python-virtual-environments) for Python. |
| 145 | + |
| 146 | +If this is the first time, download the ssh service from CSCS GitHub: |
| 147 | + |
| 148 | +```bash |
| 149 | +git clone https://github.com/eth-cscs/sshservice-cli |
| 150 | +cd sshservice-cli |
| 151 | +``` |
| 152 | + |
| 153 | +The next step is to use either the bash or python scripts: |
| 154 | + |
| 155 | +=== "bash" |
| 156 | + Run the bash script in the `sshservice-cli` path: |
| 157 | + |
| 158 | + ``` |
| 159 | + ./cscs-keygen.sh |
| 160 | + ``` |
| 161 | + |
| 162 | +=== "python" |
| 163 | + |
| 164 | + The first time you use the script, you can set up a python virtual environment with the dependencies installed: |
| 165 | + |
| 166 | + ```bash |
| 167 | + python3 -m venv mfa |
| 168 | + source mfa/bin/activate |
| 169 | + pip install -r requirements.txt |
| 170 | + ``` |
| 171 | + |
| 172 | + Therafter, activate the venv before using the script: |
| 173 | + |
| 174 | + ```bash |
| 175 | + source mfa/bin/activate |
| 176 | + python cscs-keygen.py |
| 177 | + ``` |
| 178 | + |
| 179 | +For both approaches, follow the on screen instructions that require you to enter your username, password and the six-digit OTP from the authentifactor app on your phone. |
| 180 | +The script generates the key pair (`cscs-key` and `cscs-key-cert.pub`) in your `~/.ssh` path: |
| 181 | + |
| 182 | +```bash |
| 183 | +> ls ~/.ssh/cscs-key* |
| 184 | +/home/bobsmith/.ssh/cscs-key /home/bobsmith/.ssh/cscs-key-cert.pub |
| 185 | +``` |
| 186 | + |
| 187 | +#### Getting keys via the web app |
| 188 | + |
| 189 | +Access the SSHService web application by accessing the URL, [sshservice.cscs.ch](https://sshservice.cscs.ch). |
| 190 | + |
| 191 | +1. Sign in with username, password and OTP |
| 192 | +2. Select "Signed key" on the left tab and click on "Get a signed key" |
| 193 | +3. On the next page a key pair is generated and ready to be downloaded. Download or copy/paste both keys. |
| 194 | + |
| 195 | +Once generated, the keys need to be copied from where your browser downloaded them to your `~/.ssh` path, for example: |
| 196 | +```bash |
| 197 | +mv /download/location/cscs-key-cert.pub ~/.ssh/cscs-key-cert.pub |
| 198 | +mv /download/location/cscs-key ~/.ssh/cscs-key |
| 199 | +chmod 0600 ~/.ssh/cscs-key |
| 200 | +``` |
| 201 | + |
| 202 | +### Step 2: log in with the generated keys |
| 203 | + |
| 204 | +Set up a passphrase on the private key: |
| 205 | +``` |
| 206 | +ssh-keygen -f ~/.ssh/cscs-key -p |
| 207 | +``` |
| 208 | + |
| 209 | +Add the key to the SSH agent: |
| 210 | +``` |
| 211 | +ssh-add -t 1d ~/.ssh/cscs-key |
| 212 | +``` |
| 213 | + |
| 214 | +??? warning "Could not open a connection to your authentification agent" |
| 215 | + If you see this error message, the ssh agent is not running. |
| 216 | + You can start it with the following command: |
| 217 | + ``` |
| 218 | + eval $(ssh-agent) |
| 219 | + ``` |
| 220 | + |
| 221 | +Once the key has been configured, you can log in to CSCS' login system Ela: |
| 222 | +```bash |
| 223 | +# log in to ela.cscs.ch |
| 224 | + |
| 225 | + |
| 226 | +# then jump to a cluster |
| 227 | +> ssh clariden |
| 228 | +``` |
| 229 | + |
| 230 | +#### Frequently encountered issues |
| 231 | + |
| 232 | +??? warning "too many authentification failures" |
| 233 | + You may have too many keys in your ssh agent. |
| 234 | + Remove the unused keys from the agent or flush them all with the following command: |
| 235 | + ```bash |
| 236 | + ssh-add -D |
| 237 | + ``` |
| 238 | + |
| 239 | +??? warning "Permission denied" |
| 240 | + This might indicate that they key has expired. |
| 241 | + |
| 242 | + |
| 243 | +??? warning "Could not open a connection to your authentication agent" |
| 244 | + If you see this error when adding keys to the ssh-agent, please make sure the agent is up, and if not bring up the agent using the following command: |
| 245 | + ```bash |
| 246 | + eval $(ssh-agent) |
| 247 | + ``` |
| 248 | + |
| 249 | +!!! todo |
| 250 | + We need a "best practices"/"hints and tips" section for setthing up `~/.ssh/config` |
0 commit comments