{{ appConfig.logo.shortName }}
Typus©

2FA Diagram

Last Updated: May 19, 2025

This document provides an overview of the two-factor authentication (2FA) system in the Typus Development Framework.

Overview

Two-factor authentication (2FA) adds an extra layer of security to the authentication process by requiring users to provide two different authentication factors: something they know (password) and something they have (a mobile device or email access).

2FA Methods

Typus supports multiple 2FA methods:

  1. APP: Time-based one-time passwords (TOTP) using authenticator apps like Google Authenticator or Authy
  2. EMAIL: One-time codes sent via email

2FA Setup Flow

EmailServiceDatabaseTwoFactorAuthAuthServiceAPIFrontendUserEmailServiceDatabaseTwoFactorAuthAuthServiceAPIFrontendUseralt[APP Method][EMAIL Method]Request 2FA setupPOST /auth/2fa/setupsetup2FA(userId, type)setup(userId, type)Generate secret keyStore temporary secretReturn secret and otpauthUrlSecret and otpauthUrlQR code dataDisplay QR codeEnter verification codePOST /auth/2fa/enableenable2FA(userId, code, type)enable(userId, code, type)Verify code against secretEnable 2FA for userConfirmation2FA enabledSuccess response2FA enabledShow success messageGenerate verification codeSend verification emailEmail with verification codeStore temporary codeEmail sent confirmationEmail sentPrompt for codeEnter verification codePOST /auth/2fa/enableenable2FA(userId, code, type)enable(userId, code, type)Verify codeEnable 2FA for userConfirmation2FA enabledSuccess response2FA enabledShow success message

2FA Login Flow

EmailServiceDatabaseTwoFactorAuthAuthServiceAPIFrontendUserEmailServiceDatabaseTwoFactorAuthAuthServiceAPIFrontendUserUser has already entered valid credentialsalt[APP Method][EMAIL Method]alt[Invalid Code][Valid Code]login(email, password)Check if 2FA is enabled2FA is enabledrequiresTwoFactor: true, tempToken2FA requiredPrompt for authenticator codeEnter code from authenticator appgenerateEmailCode(userId)Store verification codeSend verification emailEmail with verification codePrompt for email codeEnter code from emailPOST /auth/2fa/verifyverify2FA(tempToken, code, type)verify(tempToken, code, type)Invalid codeAuthentication failedError messageShow error messageVerify codeCode verifiedGenerate tokensTokens generatedAuthentication successfulUser data and tokensAuthentication successfulRedirect to dashboard

APP Method (TOTP)

The APP method uses the Time-based One-Time Password (TOTP) algorithm:

  1. Setup:

    • System generates a secret key
    • User scans QR code with authenticator app
    • User verifies setup by entering a code from the app

  2. Verification:

    • User enters the current code from their authenticator app
    • System validates the code against the stored secret
    • Code changes every 30 seconds for security

EMAIL Method

The EMAIL method uses one-time codes sent via email:

  1. Setup:

    • System sends a verification code to the user's email
    • User enters the code to confirm access to the email

  2. Verification:

    • System generates a random 6-digit code
    • Code is sent to the user's email address
    • User enters the code to complete authentication
    • Codes expire after 5 minutes

Security Considerations

  1. Secret Storage: 2FA secrets are securely stored in the database
  2. Temporary Tokens: Temporary tokens are used during the 2FA verification process
  3. Rate Limiting: Verification attempts are rate-limited to prevent brute force attacks
  4. Expiration: Verification codes expire after a short period
  5. Backup Codes: Recovery options are available if users lose access to their 2FA method

Disabling 2FA

Users can disable 2FA through their account settings:

DatabaseTwoFactorAuthAuthServiceAPIFrontendUserDatabaseTwoFactorAuthAuthServiceAPIFrontendUserRequest disable 2FAPOST /auth/2fa/disabledisable2FA(userId, type)disable(userId)Disable 2FA for userConfirmation2FA disabledSuccess response2FA disabledShow success message

Implementation Details

The 2FA system is implemented using a strategy pattern:

  1. Common Interface: All 2FA methods implement a common interface
  2. Method Selection: The appropriate method is selected based on user preferences
  3. Extensibility: New 2FA methods can be added by implementing the interface

Conclusion

The two-factor authentication system in Typus provides a robust security layer that can be customized to meet different security requirements. By supporting multiple 2FA methods, the system offers flexibility while maintaining strong security standards.