Implement a Robust Multi-Factor Authentication (MFA) System for Enhanced Account Security

[tnramalho]

Use case

As a user and application administrator,

  I want to enable and manage multi-factor authentication (MFA) for my account,
  
  So that I can add an extra layer of security to protect my account from unauthorized access.

Acceptance Criteria:

1. Enabling MFA via Authenticator Apps:

   • AC1: Users can enable MFA from their account settings.

   • AC2: The setup process includes generating a QR code that can be scanned using authenticator apps like Google Authenticator or Authy.

   • AC3: Users must enter a valid Time-based One-Time Password (TOTP) code from their authenticator app to confirm and activate MFA.

   • AC4: Upon successful setup, MFA is marked as enabled for the user’s account.

2. MFA During the Login Process:

  • AC5: After entering valid login credentials, users with MFA enabled are prompted to enter a TOTP code.
  
  • AC6: Access to the application is granted only after a valid TOTP code is provided.
  
  • AC7: Users can opt to remember trusted devices, reducing the frequency of MFA prompts on those devices.
  
  • AC8: The system handles scenarios where MFA is required but the user fails to provide a valid TOTP code within a specified number of attempts.

3. Backup Codes for MFA:

  • AC9: Upon enabling MFA, users are provided with a set of one-time-use backup codes for account recovery.
  
  • AC10: Backup codes can be regenerated by the user, which invalidates the previous set.
  
  • AC11: Users are prompted to securely store backup codes and are notified about their one-time usability.
  
  • AC12: Backup codes can be used as an alternative to TOTP codes during the login process if the authenticator app is unavailable.

4. MFA Management Interface:

  • AC13: Users can view their current MFA status and associated authenticator apps in their account settings.
  
  • AC14: Users can disable MFA, which requires re-authentication and confirmation to prevent accidental or unauthorized disabling.
  
  • AC15: Users can regenerate backup codes from the management interface.
  
  • AC16: The interface provides clear instructions and support for managing MFA settings.

5. Security and Compliance:

  • AC17: MFA secrets and backup codes are securely stored using encryption and best security practices.
  
  • AC18: The system enforces strong authentication flows to prevent vulnerabilities such as man-in-the-middle attacks.
  
  • AC19: Compliance with relevant security standards and regulations (e.g., NIST guidelines) is ensured in the MFA implementation.

Proposal

This feature is crucial for enhancing authentication security and mitigating risks of unauthorized access. Implementing MFA aligns with modern security standards and best practices, ensuring compliance with regulations like NIST guidelines

[tnramalho]

Should we consider implementation of a adaptive mfa as well and consider calculates an overall confidence score like NewDevice, ImpossibleTravel, UntrustedIP or a combination of all 3 factors?

ref: https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa

[gabrielrangel95]

@tnramalho I think for now we should focus on a simplified version of the 2FA.
We can build the adaptative MFA in a second version

[tnramalho]

Here are some suggestions of implementation for us to start discussing.

*The blocks in orange are not defined in the sequence diagram, since we still need to validate if we gonna implement it now or not, but i added to the flow diagram to make easy to understand where it would fit

The basic Success sequence would be follow the following step that will be split in 3 flows.

1 - Authentication with username and password using auth local
2 - System checks MFA enables if so retunes temp token
3 - Assuming authApp was defined to be used, we start auth app flow
4 - Generate QR code, Scan QR Code, add to AuthApp, verify code, enable mfa and generate final token
5 - Then on JWT strategy we would validate jwt token have all flags to confirm mfa happened

Flow 1 - Auth Local Flow

On this flow we authenticate using username and password, and add the JWT the MFA this user needs to complete authentication.

sequenceDiagram

participant User
participant LS as Login System
participant MFA as MFA Service
participant AL as Auth Local Strategy
participant AV as Auth Local Validate
participant UMT as User MFA Types

User->>LS: Login Request
LS-->>AL: Local Authentication
AL-->>AV: Validate
AV-->>AL: Yes

alt System has MFA required?
    AL-->>UMT: Get User MFA types
    UMT-->>AL: User MFA Types (authApp/SMS)
    AL-->>AL: Add MFA types to user
end
AL-->>User: Temp JWT with user mfa flag not verified

Flow 2 - MFA Auth App Flow

Register the QRCode on AuthApp and verify its code

sequenceDiagram
    participant User
    participant LS as Login System
    participant AL as Auth Local Strategy
    
    participant UMT as User MFA Types
    participant QR as MFA controller
    participant APP as Authenticator App

    User->>LS: Login Request
    LS-->>AL: Local Authentication
    AL-->>LS: Temp Token { mfaAuthAppVerified=false }
    
        alt No MFA Configured
            LS->>User: Prompt to enable MFA
            User->>LS: Accepts MFA Setup
            LS->>QR: Generate QR Code
            QR->>LS: Return QR Code
            LS->>User: Show QR Code
            User->>APP: Scan QR Code
            APP->>User: Generate MFA Code
            User->>LS: Enter MFA Code
            LS->>QR: Verify MFA Code    
            QR->>QR: Register MFA to user and enable authApp
            QR-->>LS: New JWT with MFA Verified Flag { mfaAuthAppVerified=true }
        
        else MFA Already Setup
            User->>LS: Enter MFA Code
            LS->>QR: Verify MFA Code
            QR-->>LS: New JWT with MFA Verified Flag { mfaAuthAppVerified=true }
        
        end
    LS->>User: Access Granted 

Flow 3 - JWT Strategy

With new JWT token validate if token is valid based on all flags

sequenceDiagram
    participant User
    participant LS as Login System
    participant MFA as MFA Service
    participant AL as JWT Strategy
    participant AV as User Lookup
    participant UMT as User MFA Types
    User->>LS: Request with JWT
    LS-->>AL: JWT validation
    AL-->>AV: Get user
    AV-->>AL: Return user
    alt System has MFA required?
        AL-->>UMT: Get User MFA types
        UMT-->>AL: User MFA Types (authApp/SMS)
        AL-->>AL: Check if JWT claim has the flags needed has verified
    end
    AL-->>User: Valid jwt or Error

@MrMaz tell me what you think.