Merge branch 'issue_161'

docs/getting_started/get_uppmax_2fa.md

@@ -7,11 +7,87 @@ tags:
 
 # Setting up two factor authentication for UPPMAX
 
+## Why
+
+For security reasons you will have to use a two factor authentication system
+if you are a) connecting to UPPMAX from outside of Sweden, or b) connecting
+from a network within Sweden that does not support forward and reverse DNS
+lookups (due to a misconfiguration in your network, you can ask your
+internet service provider about this). More information about why can be
+found
+[here](https://www.uu.se/en/centre/uppmax/get-started/2-factor/why-2-factor).
+
+## Procedure
+
 ???- question "Prefer a video?"
 
     Watch [the YouTube video 'Get your UPPMAX 2FA'](https://youtu.be/eSn0kLkU5Dc)
 
-Follow the guide [Setting up two factor authentication for UPPMAX](https://www.uu.se/en/centre/uppmax/get-started/2-factor).
+
+By requiring a second factor, typically a cell phone or other physical device, it becomes much harder for an attacker to gain access to your account if they somehow have gotten hold of your password (which in this case is the 1:st factor). Instructions to set this up follows below.
+
+Some of the points in the list below are link you can click on for more detailed instructions.
+
+### 1. Select an app to use
+
+Select an app to use.
+See [here](https://www.uu.se/en/centre/uppmax/get-started/2-factor/app-selection)
+for an overview.
+
+### 2. Go to https://suprintegration.uppmax.uu.se/bootstrapotp/
+
+Go to <https://suprintegration.uppmax.uu.se/bootstrapotp/>.
+
+???- question "How does this look like?"
+
+    Here is how <https://suprintegration.uppmax.uu.se/bootstrapotp/>
+    looks like:
+
+    ![https://suprintegration.uppmax.uu.se/bootstrapotp](suprintegration_uppmax_uu_se_bootstrapotp.png)
+
+Click on 'Continue'.
+
+### 3. You will be sent to SUPR
+
+You should be sent to
+[SUPR](https://www.uu.se/en/centre/uppmax/get-started/2-factor/supr).
+
+In case you are not logged in already, log in to SUPR.
+
+### 4. Press the button 'Prove My Identity to UPPMAX'
+
+Acknowledge to SUPR that they may tell UPPMAX who you are,
+by pressing the button "Prove My Identity to UPPMAX" on the page.
+
+### 5. Scan the QR-code with your 2FA app
+
+Scan the QR-code with a second factor authentication app of your choice
+in your smart phone. For example "Google Authenticator" by Google
+or "Authy" by Authy Inc.
+
+More details [here](https://www.uu.se/en/centre/uppmax/get-started/2-factor/qr).
+
+### 6. Enter the code on the webpage
+
+Your application will show you a code, enter this code on the same webpage.
+
+### 7. See acknowledgement that the new two factor has been registered.
+
+You should see an acknowledgement that the new two factor has been registered.
+
+### 8. Wait for a confirmation email
+
+It will take some time before your second factor is imported to our systems.
+You should get a mail within a few minutes notifying you of the newly registered token.
+
+### 9. You will be able to use it to login
+
+When it has been activated you will be able to use it to login
+by giving the current code from the app when asked for.
+
+Advanced usage and alternative setups (without smart devices).
+
+Once your token has been activated you can use the temporary code generated by your application to login.
 
 After this procedure, it takes around 15 minutes before you can use
 the 2FA to log in.
@@ -31,6 +107,14 @@ the 2FA to log in.
 
     ![Authentication failed](./img/get_uppmax_2fa_authentication_failed_directly_after_new_2fa.png)
 
-## Link
+## Troubleshooting
+
+Troubleshooting
+
+Some of the common problems we've seen include
 
-- [Setting up two factor authentication for UPPMAX](https://www.uu.se/en/centre/uppmax/get-started/2-factor)
+- Not having an account at UPPMAX. This is required to get the second factor for your account.
+- Using a device having it's time set differently from our systems. There are services on the internet (e.g. https://time.is/) you can visit from the device you try to manage the code on that will show you if your device settings are problematic.
+- Noting the code given at first and trying to use it every time when asked for a code. The code to give will change every thirty second and you should give whatever code is shown at the time.
+- Expecting something else to be sent to you. You register the new second factor as part of the process. A confirmation mail is sent as well, but this is mostly to let you know in case your account details in SUPR have gone astray and someone else has registered a second factor for your account.
+- It takes a little while before your newly registered factor is usable, but this should be a matter of minutes, not days. There is no extra mail sent to let you know that the newly registered factor is usable, just the confirmation mail that mentions that it will be activated soon.