Differences

This shows you the differences between two versions of the page.

--- cn:ccr:aai:doc:2fa-en:req [2024/10/16 12:56] – [Ente Auth] monducci@infn.it
+++ cn:ccr:aai:doc:2fa-en:req [2025/03/21 08:09] (current) – monducci@infn.it
@@ Line 1: / Line 1: @@
+====== Instructions for Activating Two-Factor Authentication ======
+**WARNING:** Once two-factor authentication is activated, every login via the INFN-AAI IdP will require two factors. You can choose the first in the usual way (username/password, X.509, Kerberos-GSSAPI, SPiD, CIE), and the second will always be the TOTP (Time-based One-Time Password) code generated by the app you chose and stored the token in during the two-factor activation process.
+**WARNING:** After 10 failed OTP authentication attempts, the system will block access. You will need to request a reset of the failed attempt counter by sending an email to aai-support@infn.it.
+===== Prerequisites =====
+  - Active role
+  - An application for generating a Time-based One-Time Password (TOTP)
+==== Active Role ====
+Only employees, associates, and guests can request two-factor authentication.
+==== Application ====
+Before starting the token acquisition process, it is essential to **install** and properly **configure** an application compatible with our infrastructure, running on a **device that keeps the correct time**, synchronized with official time sources. If the device’s time is off by even half a minute, the generated TOTP may already be expired or not yet valid. Most devices are set to automatically sync with official sources via the network, but you might be on a network that blocks the NTP protocol, causing the device's clock to drift.
+The only compatible applications are:
+  * **privacyIDEA** Authenticator: available for iOS and Android from their respective stores.
+  * **Ente Auth**: the first choice. Multi-platform. It is also recommended by CERN, which can make life easier for CERN users.
+  * **BitWarden**: available for both mobile and desktop **only if connected to a "self-hosted" account set up at https://vault.infn.it/**.
+**WARNING:** Google Authenticator is NOT supported. Microsoft Authenticator should NOT be used (both store the key in plain text in their cloud).
+**WARNING:** Bitwarden connected to the INFN "vault" is allowed **only if used for one authentication factor**. In other words, it is **FORBIDDEN** as a TOTP generator if you store your INFN-AAI credentials there.
+Detailed instructions on how to install and configure these three applications are available [[cn:ccr:aai:doc:2fa:app|on this wiki page]].
+----
+===== Enabling Two-Factor Authentication =====
+The two-factor authentication activation process consists of two seemingly separate actions that are closely connected:
+  - Generating a **token** (performed by the MFA server);
+  - Storing the **token** in the application.
+**Note**
+Since during the first week of optional two-factor activation we observed a significant number of failed token storage attempts, we modified the process by adding a verification step to ensure the token is correctly stored and used before activating two-factor authentication.
+==== Token Generation ====
+To generate a token, log in to the web service at:
+https://mfa.app.infn.it/
+using your INFN-AAI credentials. After entering your credentials in the standard INFN login window,
+{{ :cn:ccr:aai:doc:2fa:loginaai.png?200 | Login AAI}}
+you will be asked to confirm access:
+{{ :cn:ccr:aai:doc:2fa:login.png?200 |Login}}
+On your first login, the only available action will be to request a token.
+In the window, select: **Enroll Token**.
+{{ :cn:ccr:aai:doc:2fa:enrolltoken01.png?400 |Enroll Token}}
+Next, specify the following values:
+Enroll a new token
+  - TOTP: Time-based One-Time Password
+Token data
+  - OTP length: 6
+  - Timestep: 30
+and click the **Enroll Token** button.
+{{ :cn:ccr:aai:doc:2fa:enrolltoken02.png?400 |Enroll Token}}
+The next screen will show you a QR code to import into your app.
+{{ :cn:ccr:aai:doc:2fa:verify_token.png?400 |Enroll Token}}
+By clicking the link "The OTP Key," you can view the "secret" or "seed" encoded in a couple of formats, for manual configuration in apps that cannot use QR codes.
+{{ :cn:ccr:aai:doc:2fa:view_otp_key.png?400 |View OTP key}}
+**WARNING:** The secret/seed is only **one** of the data elements in the QR code and is not sufficient for manual configuration by itself. If the app you are using to generate the TOTP cannot import data from the QR code, immediately save the Base32-encoded key.
+If you've chosen an app that can read a QR code, you can simply scan it to import the information (instructions for some applications are available [[cn:ccr:aai:doc:2fa:req#importare_il_qr|here]]).
+==== Enrollment Verification ====
+In this window, you will find a **"Verify Token"** button under a **"Please enter a valid OTP value of the new token"** field. This is used to verify that the token was correctly registered in your app and that it produces a valid TOTP.
+The token acquisition process will only complete if this final verification step is successful.
+The session timeout on this webpage is 15 minutes, so it’s essential to save the information before the timeout expires.
+If the TOTP produced by your application is incorrect (or you mistype it), an error popup will appear as shown in the image, and you can correct the TOTP or switch to a supported app.
+{{ :cn:ccr:aai:doc:2fa:verify_token_ko.png?400 |Verify Token KO}}
+If you cannot enter the correct TOTP but have saved the information, you can log back in at https://mfa.app.infn.it/ and complete the token verification by clicking the serial number of the token to be verified:
+{{ :cn:ccr:aai:doc:2fa:my_tokens.png?400 |My Tokens}}
+and entering the correct TOTP above the blue "Verify Token" button:
+{{ :cn:ccr:aai:doc:2fa:verify_enroll.png?400 |Verify Enrollment}}
+Completing the token acquisition process:
+{{ :cn:ccr:aai:doc:2fa:verify_enroll_ok.png?400 |Verify Enrollment OK}}
+and you will receive a confirmation email.
+==== Importing the QR Code ====
+The simplest way to register the token in your app is to use a smartphone (or tablet) app capable of using the camera to import the QR code data.
+=== Ente Auth ===
+The Ente Auth smartphone app has a start page with a "Scan a QR Code" button:
+{{ :cn:ccr:aai:doc:2fa:enteauthapp1.png?200 |}}
+This button directly accesses the camera, and as soon as the QR code is scanned, it generates a TOTP.
+{{ :cn:ccr:aai:doc:2fa:enteauthapp2.png?200 |}}
+If you've set up an account on ente.io as described in [[cn:ccr:aai:doc:2fa:app|this wiki page]], all instances of Ente Auth linked to that account will generate the same TOTP.
+[[cn:ccr:aai:doc:2fa:req#verifica_dell_enrollment| return to enrollment verification]]
+=== Bitwarden (mobile app, with camera access) ===
+Select: Set up TOTP.
+{{ :cn:ccr:aai:doc:2fa:bitwaredapp1.png?200 | Bitwarden App}}
+Allow the app to use the camera.
+{{ :cn:ccr:aai:doc:2fa:bitwaredapp2.png?200 | Bitwarden App - Camera Access}}
+Assign a name to the token and save it.
+{{ :cn:ccr:aai:doc:2fa:bitwaredapp3.png?200 | Bitwarden App - Token Saving}}
+The saved token will then be displayed like this:
+{{ :cn:ccr:aai:doc:2fa:bitwaredapp4.png?200 | Bitwarden App - Token Display}}
+=== PrivacyIdea ===
+To import the QR code into the PrivacyIdea app, simply click the central icon and scan the QR Code.
+{{ :cn:ccr:aai:doc:2fa:privacyideaapp.png?200 |PrivacyIdeaApp}}
+[[cn:ccr:aai:doc:2fa:req#verifica_dell_enrollment| return to enrollment verification]]
+----
+===== Manual Configuration: Importing the OTP Key =====
+The QR code contains a series of necessary details for properly configuring the TOTP generator. If you wish to use a TOTP generator that doesn’t support QR codes (like supported PC apps or the web interface to the INFN "vault"), you’ll need to properly format the string for its configuration.
+The string must be formed by concatenating:
+  * %%otpauth://totp/?secret=%%
+  * <The BASE32 encoded OTP Key>
+  * &algorithm=sha256&period=30&digits=6&issuer=INFN-AAI
+The string should look like this:
+<code>
+  otpauth://totp/?secret=2UCHU2WHNR3S52W7Z6DRQ5XCGWQZ5XAFB6C3JD5F6DSJZ53TL5FA&algorithm=sha256&period=30&digits=6&issuer=INFN-AAI
+</code>
+If you chose a 60-second period or
+ an 8-digit TOTP, change the period and digits to match your choice.
+Below the detail of the manual configuration for the supported apps.
+==== Ente Auth ====
+Ente Auth can import a key from a file in text format.
+You must therefore create a text file and insert the string obtained from the concatenation of the above information into one line.
+After creating and saving the file
+  - open the application
+  - pressing on the three lines at the top left (open navigation menu)
+  - open the down arrow next to the "Data" item
+  - select: "Import codes"
+  - choose: "Plain text"
+  - press: "Select file"
+  - select the file created previously
+If the operation was successful, a window will appear saying:
+Yay!
+You have imported 1 codes!
+[[cn:ccr:aai:doc:2fa-en:req#enrollment_verification| Return to enrollment verification]]