Type: Technical Documentation
Affects Version/s: None
Component/s: Application Security > Multi-Factor Authentication
Sprint:Iteration 38, Iteration 39, Iteration 40
Type of Documentation:User
This development is part of the creation of a component that allows the activation of Multi-Factor-Authentication (from now on: MFA) in the portal. When accessing the portal using the Login UI, a second authentication factor will be requested to verify the user's identity beyond the password.
This feature allows to activate an Timebased-OTP verifier for MFA, it only appears when MFA is already enabled. So we would have different scenarios to consider when a user logs into the portal:
- Do not enable MFA: User will access the portal using mail/password
- Enable MFA (and therefore activate Email OTP as a verifier): User will access the portal using mail/password and then the verification via email would be shown. The end user will be shown a screen where he/she should enter the code received in his/her mail account.
- Enable MFA (and therefore activate Email OTP as a verifier) and configure Timebased OTP Verifier:
- If the user has not configured in his/her Account Settings the Timebased OTP Verifier: User will access the portal using mail/password and then the verification via email would be shown
- If the user has configured in his/her Account Settings the Timebased OTP Verifier: User will access the portal using mail/password and then he/she will be able to choose between access using the Email Verification or the Timebased Verification. By default, the Verifier with the highest order in the configuration will be shown, and we will add an option to switch to the second active Verifier. On the screen of the second active verifier there will be a link to the third one if that exists and so on.
As end user if Timebased OTP verifier has been activated for the Instance, he/she will have to configure his/her Timebased OTP at Account Settings, a new tab will appear where it will be available an option to scan a QRCode or enter manually a Shared-Secret code using the recommended application: Google App Authenticator. That application will provide a code that must be entered to have the Timebased OTP verifier configured.
During the login process, the user must simply enter the code provided by the application at the time of access.
Once configured, the user can go back to Account Settings to delete their configured code and regenerate a new one again.
The end user also can remove the Timebased OTP verifier configuration.
As Instance Administrator, to activate this functionality there's a new option at Instance Settings - Multi-Factor Authentication. There are also several configurable fields to set up the Timebased OTP algorithm to use (we're following the actual specification: https://tools.ietf.org/html/rfc6238)
There are several modules to take into account for this functionality:
- multi-factor-authentication-spi: This module defines the necessary interfaces to work with MFA, in this case the TimeBasedOTPBrowserSetupMFAChecker (located at "multi-factor-authentication-timebased-otp-web") is of type SetupMFAChecker and also BrowserMFAChecker
- multi-factor-authentication-web: This module defines the logic common to the whole portal related to MFA, through MFAPolicy the activated verifiers will be checked and with LoginMVCActionCommand the Login action is intercepted in order to track MFA verifiers.
Also in this module, we track the available setup checkers and generate a new entry for the final user at Account settings (check this package)
- multi-factor-authentication-timebased-otp-api: This module defines the Model and Persistence layer to track the Timebased OTP verifier for each user.
- multi-factor-authentication-timebased-otp-service: This module defines the Service layer to work with the Timebased OTP entry verifier.
- multi-factor-authentication-timebased-otp-web: This module defines the specific Portlet to show the Timebased OTP verifier and also the setup verification for the final user.