====== First-time 2FA Setup via a Personal Computer ======

===== Preliminary Actions =====

You need to install a //program// on your personal computer which will 

  * store the **secret key** that the IL authentication system will share with you
  * calculate TOTP passcodes using the **secret key** as a seed

We advise Free Softwares such as [[https://keepassxc.org/|KeePassXC]] (multiplatform with GUI) or the [[https://www.nongnu.org/oath-toolkit/|OATH Toolkit]] (GNU/Linux terminal), but you are free to choose any programs that implement the open OTP standards. 

===== Setup =====

==== Step 1 ====
Navigate to any of the Lorentz Institute SSO web applications, for instance our [[https://remote.lorentz.leidenuniv.nl|Remote Workspace]].

You will be redirected automatically to the Lorentz Institute Identity Provider login page as in **Figure 1**.
<figure>{{:institute_lorentz:ilidp1.png?direct&400|}}<caption>Identity Provider login page</caption></figure>

==== Step 2 ====

Enter your IL credentials to sign in. Upon successful login, you will be redirected to a page containing a QR code. Click on "Unable to Scan?" to display your shared **secret key** and the other parameters to input in your OTP program to set it up (Figure 2).

Note the secret key, the algorithm, the number of digits, and the time interval. You will need them in Step 3.

<figure>{{:institute_lorentz:ilidp2_blur.png?direct&400|}}{{:institute_lorentz:ilidp3_mod.png?direct&430|}}<caption>TOTP Setup Page (QR code and other sensitive information deliberately blurred)</caption></figure>

==== Step 3 ====

Open KeePassXC (installed on all IL workstations), create a new passwords database if you do not want to use an existing one and click on //Entries -> TOTP -> Set Up TOTP//. Insert your private key, algorithm, time interval and number of digits from Step 2 and confirm by clicking on `OK'. 

<figure>{{:institute_lorentz:keepassxc1.png?direct&500|}}{{:institute_lorentz:keepassxc2.png?direct&200|}}<caption>TOTP Setup with KeePassXC. Use the TOTP settings described in Step 2.</caption></figure>

Generate a OTP by clicking on //Entries -> TOTP -> Show TOTP//. Insert this TOTP in the //One-time code// form input and, if you wish, a label in the form input called //Device Name//. This label is meant to help you keep track with which device the **secret key** has been shared. Click on //Submit//.

<figure>{{:institute_lorentz:keepassxc3.png?direct&500|}}{{:institute_lorentz:keepassxc4.png?direct&200|}}{{:institute_lorentz:keepassxc5.png?direct&400|}}<caption>TOTP generation KeePassXC and final 2FA setup on the Lorentz Institute Identity Provider</caption></figure>

==== Step 4 ====
If Step 3 succeeds (errors might occur if there is too much lag time, i.e. the OTP expired), the system will send you an email to your private (not @lorentz) e-mail address with [[institute_lorentz:verify_identity|precise instructions]] on how to verify your identity. If your identity  cannot be validated, you will not be granted access to the system.

<figure>{{:institute_lorentz:idp4_email1.png?direct&344|}}<caption>Verify your private email address</caption></figure>

==== Step 5 ====
Verify your identity by visiting your private email inbox. You should have received an email from the Lorentz Institute Identity Provider ((Details of this email are not disclosed here to prevent phishing.)). Open that email and __copy__ (for instance using on most platforms Control-C or right-mouse click copy) the secret code in the body of the message. Visit https://www.lorentz.leidenuniv.nl/idp/ and __paste__ (on most platforms Control-P or right-mouse click paste) the secret code in the white text area.  Click on `Submit'. Your identity is now verified.

<figure>{{:institute_lorentz:idp4_email2.png?direct&400|}}{{:institute_lorentz:idp4_email3_mod.png?direct&380|}}{{:institute_lorentz:idp4_email4.png?direct&380|}}<caption>Screenshot of e-mail verification process.</caption></figure>


==== Step 6 ====

Click on //Back to application// to redirect your browser to the Lorentz Institute SSO web application from which you started the whole process or close the browser. Your setup is complete. 

===== Problems and Solutions =====

|I cannot setup 2FA/access the system| Make sure we have your private email address on record|
|I lost my smartphone/PC with my OTP secret|Notify <support@lorentz.leidenuniv.nl> \\ [[:when_you_are_new_at_the_lorentz_institute|Change]] your IL credentials |
|How do I disable 2FA?| 2FA is mandatory on all SSO web services and to access our SSH server |
|My TOTP is incorrect| Make sure your phone's (PC's) clock is synchronised to the SSH server time and you scanned/copied all TOTP settings correctly |
|My OTP secret is compromised| Notify <support@lorentz.leidenuniv.nl> \\ [[:when_you_are_new_at_the_lorentz_institute|Change]] your IL credentials|