====== First-time 2FA Setup via a Smart Phone ======

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

You need to install an //app// on your Smart Phone 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 Software apps such as [[https://freeotp.github.io/|FreeOTP]] (download links below), but you are free to choose any apps that implement the open OTP standards. 

|[[https://play.google.com/store/apps/details?id=org.fedorahosted.freeotp&hl=nl&gl=US|{{:services:android.png?nolink&150|}}]]|[[https://apps.apple.com/nl/app/freeotp-authenticator/id872559395#?platform=iphone|{{:services:apple.png?nolink&150|}}]]|[[https://f-droid.org/en/packages/org.fedorahosted.freeotp/|{{:services:2fa:get-it-on.png?nolink&150|}}]] |

Other mobile apps known to work with our system are //google authenticator// and //andOTP//. However, any app implementing the open TOTP standard will do.

|:!: Leiden University suggests the use of the [[https://www.netiq.com/documentation/advanced-authentication-63/smartphone-applications/data/bookinfo.html|NetIQ Advanced Authentication App]] for 2FA. Should you want to install this proprietary software, you should know that  the [[https://www.netiq.com/documentation/advanced-authentication-62/server-user-guide/data/totp.html|QR codes generated by this app differ]] from those generated by Free TOTP apps and can lead to 2FA problems if you scan a NetIQ-generated QR code with a Free app.|
===== 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 to be scanned via your OTP mobile app (Figure 2). The QR code contains your shared **secret key** and other useful information regarding the OTP algorithm used by the IL authentication infrastructure. 

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

==== Step 3 ====

Open your OTP app and scan the QR code. Your secret key will now be stored on your phone and a new entry called **Lorentz Institute Intranet** with its corresponding TOTP will be created in your app (Figure 3). 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:freeOTP_mod.png?direct&190|}}{{:institute_lorentz:ilidp2_blur_code.png?direct&400|}}<caption>FreeOTP entry for **Lorentz Institute Intranet** and its corresponding TOTP. Upon expiration, a new TOTP will be automatically generated (left). 2FA Setup page with TOTP and label inserted (right).</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>Verrify 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|