Multi-Factor Authentication (MFA) adds an extra layer of security to your Chatwoot account by requiring a second form of verification in addition to your password. This significantly reduces the risk of unauthorized access, even if your password is compromised.

Chatwoot supports Time-based One-Time Password (TOTP) authentication using standard authenticator apps, as well as backup codes for emergency access.

Prerequisites

Before enabling MFA:

1. MFA must be enabled at the system level by your administrator

2. You need a TOTP-compatible authenticator app such as:

   • Google Authenticator

   • Microsoft Authenticator

   • Authy

   • 1Password

   • Any other TOTP-compatible app

User Flows

- Enabling MFA from Profile Page

This flow allows users to enable two-factor authentication for their account.

Step-by-Step Process:

1. Navigate to MFA Settings

• Log in to your Chatwoot account

• Click on your profile avatar in the bottom-left corner

• Select "Profile Settings"

• Navigate to the "Two-Factor Authentication" tab

1. Start MFA Setup

• Click the "Enable Two-Factor Authentication" button

• The system will generate a unique secret key for your account

  

3. Configure Authenticator App

• A QR code will be displayed on the screen

• Open your authenticator app and scan the QR code

• Alternatively, manually enter the secret key if you can't scan the QR code

4. Verify Setup

• Your authenticator app will generate a 6-digit code

• Enter this code in the verification field

• Click "Verify and Enable"

5. Save Backup Codes

• Upon successful verification, you'll receive 10 backup codes

• Important: Save these codes in a secure location immediately

• Each backup code can only be used once

• Options available:

• Copy all codes to clipboard

• Download as a text file

• Print for physical storage

  

6. Confirmation

• MFA is now enabled for your account

• You'll see a status indicator showing "Two-Factor Authentication is Enabled"

  

- Disabling MFA from Profile Page

Users may need to disable MFA when switching devices or authentication methods.

Step-by-Step Process:

1. Navigate to MFA Settings

• Go to Profile Settings → Two-Factor Authentication

2. Initiate Disable Process

• Click on "Disable Two-Factor Authentication" button

• A confirmation dialog will appear warning about the security implications

3. Verify Identity

• Enter your current password

• Enter a valid 6-digit code from your authenticator app (or use a backup code)

• This dual verification ensures only the account owner can disable MFA

4. Confirm Disable

• Click "Disable MFA" to confirm

• The system will remove:

• Your OTP secret

• All unused backup codes

• MFA requirement for login

Regenerating Backup Codes

Users should regenerate backup codes if they've been compromised or used up.

Step-by-Step Process:

1. Access Backup Code Management

• Navigate to Profile Settings → Two-Factor Authentication

• Locate the "Backup Codes" section

2. Initiate Regeneration

• Click "Regenerate Backup Codes"

3. Verify with Authenticator

• Enter a current 6-digit code from your authenticator app

• This ensures only authorized users can generate new codes

4. Receive New Codes

• 10 new backup codes will be generated

• All previous backup codes are immediately invalidated

• Save the new codes securely:

• Copy to clipboard

• Download as file

4. Login Flow with TOTP or Backup Code

The login process when MFA is enabled requires an additional verification step.

Step-by-Step Process:

1. Initial Login

• Enter your email and password on the login page

• Click "Sign In"

  

2. MFA Challenge

• After successful password verification, you'll be prompted for MFA

• The system provides two options:

• Use authenticator app (default)

• Use backup code (alternative)

3. Successful Authentication

• Upon successful verification, you'll be logged into your dashboard

• If using a backup code, it's marked as used and cannot be reused

• Consider regenerating backup codes if you're running low