TwoFactorSettings Documentation

Overview

The TwoFactorSettings component is an integral part of the Vantage analytics and data platform, providing users with a robust two-factor authentication (2FA) mechanism. This component enhances account security by requiring a second verification step during the sign-in process. Users can opt for authentication methods such as email codes or Time-based One-Time Passwords (TOTP) from authenticator applications.

Purpose

The primary purpose of the TwoFactorSettings component is to facilitate the configuration of two-factor authentication for user accounts. It allows users to enable or disable 2FA, choose their preferred authentication method, and manage their security settings effectively.

Settings

1. Enabled Status (enabled)

• Input Type: Boolean
• Description: This setting indicates whether two-factor authentication is currently enabled for the user's account. Changing this setting to true will activate 2FA, while setting it to false will deactivate it.
• Default Value: false

2. Authentication Method (method)

• Input Type: String
• Description: This setting specifies the method of two-factor authentication being utilized. Accepted values include:
  • email: Sends a verification code to the user's registered email address.
  • totp: Uses a Time-based One-Time Password generated by an authenticator app.
• Default Value: null (when 2FA is disabled)

3. Setup Mode (setupMode)

• Input Type: Boolean
• Description: This setting indicates whether the TOTP setup flow is currently active. In setup mode, users will be guided through the process of configuring TOTP by scanning a QR code or inputting a secret.
• Default Value: false

4. QR Code URL (qrUrl)

• Input Type: String
• Description: This setting stores the data URL of the generated QR code used during TOTP configuration. The QR code must be scanned by an authenticator app to initiate 2FA.
• Default Value: '' (empty string)

5. TOTP Secret (totpSecret)

• Input Type: String
• Description: This setting holds the secret key used to generate time-based one-time passwords for the TOTP authentication method. This secret is essential for the authenticator app to create a matching code.
• Default Value: '' (empty string)

6. Verification Code (verifyCode)

• Input Type: String
• Description: This setting captures the code input by the user from their authenticator app. It is necessary for confirming the TOTP setup during the enabling process.
• Default Value: '' (empty string)

7. Disable Mode (disableMode)

• Input Type: Boolean
• Description: This setting indicates whether the component is in a mode ready to accept confirmation for disabling 2FA. When active, users must enter their account password to confirm the unsetting of 2FA.
• Default Value: false

8. Disable Password (disablePassword)

• Input Type: String
• Description: This holds the account password that the user must enter to disable two-factor authentication. This is a security measure to confirm an intentional request to disable 2FA.
• Default Value: '' (empty string)

How It Works

When a user accesses the TwoFactorSettings component, it initially fetches the current status of two-factor authentication via an API call to /api/user/two-factor. This determines if 2FA is enabled and which method is currently in use. The component employs various state variables to manage the configuration of two-factor authentication, including enabling it, setting up TOTP, and disabling it.

Here's a brief flow of operations:

1. Loading State: On initialization, the component sets a loading state until the status fetching is complete.

2. Enabling 2FA:

   • Users can enable 2FA using either email or TOTP.
   • For email, a PUT request is made with the relevant data, activating email-based verification.
   • For TOTP, the user starts the setup, which generates a QR code that can be scanned to initialize authentication.

3. Verifying TOTP Code: After scanning the QR code, the user must enter a code from their authenticator app. A PUT request is sent to confirm this, securing the TOTP method.

4. Disabling 2FA: Users can choose to disable 2FA by entering their password for verification. This ensures an added layer of security before reverting 2FA settings.

Data Expectations

The functions within TwoFactorSettings expect the following formats for incoming and outgoing data:

• Enabling Email:

  jsonCopy

  {
      "enabled": true,
      "method": "email"
  }

• Starting TOTP Setup: No additional data is sent, as this opens a session for generating secrets and a QR code.

• Confirming TOTP:

  jsonCopy

  {
      "enabled": true,
      "method": "totp",
      "code": "123456"  // Example code from authenticator app
  }

• Disabling 2FA:

  jsonCopy

  {
      "password": "userPassword" 
  }

Use Cases & Examples

Business Use Cases

1. Enhanced Security for Sensitive Data Access: Organizations may require all users accessing sensitive analytics data to employ two-factor authentication to reduce unauthorized access risks.

2. Remote Team Configuration: Companies with employees working remotely can enforce 2FA to ensure secure remote sign-ins, helping to protect against phishing attacks.

3. Regulatory Compliance: Businesses in regulated industries may need to comply with standards requiring additional security measures, including two-factor authentication.

Example Configuration

Use Case: Enabling Authenticator App for 2FA

Scenario: A financial analyst frequently accesses sensitive reports and wishes to enhance their account security by setting up TOTP via an authenticator app.

Configuration Steps:

1. Start TOTP Setup: The analyst clicks the button for "Authenticator App." This initiates the setup:

   • API Call: POST /api/user/two-factor (returns {"secret": "ABCD1234", "otpauthUrl": "otpauth://totp/Vantage:username?secret=ABCD1234&issuer=Vantage"})

2. Scan QR Code: The analyst scans the generated QR code with their authenticator app.

3. Enter Verification Code: After scanning, the analyst receives an initial verification code from the app (e.g., 654321) and inputs it to confirm:

   • API Call: PUT /api/user/two-factor
   • Payload:
   jsonCopy

   {
       "enabled": true,
       "method": "totp",
       "code": "654321"
   }

If successful, the user receives feedback that TOTP is enabled, ensuring their account is now more secure.