Two-Factor Authentication

Overview

Two-Factor Authentication (2FA) adds an extra layer of security to your account by requiring two forms of verification when you log in: your password (something you know) and a time-based code from your mobile device (something you have). This significantly reduces the risk of unauthorized access, even if your password is compromised.

The system uses Time-based One-Time Password (TOTP) authentication, which is compatible with popular authenticator apps like Google Authenticator, Authy, Microsoft Authenticator, and others.

Accessing Two-Factor Authentication

Navigation path: Dashboard > Two-Factor Authentication

Alternative path: Dashboard > Profile > Two-Factor Authentication

Required permission: Authenticated user (own account)

Key Features

• TOTP-based Authentication: Industry-standard time-based one-time passwords
• QR Code Setup: Easy setup by scanning a QR code
• Manual Entry Option: Alternative setup method for devices without cameras
• Recovery Codes: Backup codes for account access if you lose your device
• Simple Enable/Disable: Easy to turn on or off with password confirmation
• Compatible with Popular Apps: Works with Google Authenticator, Authy, and more

Main Interface

When 2FA is Disabled

The page displays:

• Yellow warning banner: Indicates 2FA is not enabled
• Information section: Explains what 2FA is and why it's important
• Enable button: Starts the setup process

When 2FA is Enabled

The page displays:

• Green success banner: Confirms 2FA is active
• Recovery Codes section: Link to view/manage recovery codes
• Disable section: Option to turn off 2FA with password confirmation

Understanding Two-Factor Authentication

How It Works

1. You enter your username and password (first factor)
2. The system prompts for a 6-digit code (second factor)
3. You open your authenticator app on your phone
4. You enter the current code displayed in the app
5. If the code is correct, you're logged in

Why Use 2FA?

• Protection Against Password Theft: Even if someone steals your password, they can't access your account without your phone
• Defense Against Phishing: Phishing attacks that capture passwords are ineffective without the second factor
• Compliance Requirements: Many security standards require multi-factor authentication
• Peace of Mind: Know that your account is protected by more than just a password

Authenticator Apps

Compatible apps include:

• Google Authenticator (iOS, Android)
• Authy (iOS, Android, Desktop)
• Microsoft Authenticator (iOS, Android)
• 1Password (with TOTP support)
• LastPass Authenticator (iOS, Android)
• Any TOTP-compatible authenticator

Common Tasks

Task 1: Enabling Two-Factor Authentication

1. Navigate to Dashboard > Two-Factor Authentication
2. Click Enable Two-Factor Authentication
3. You'll be taken to the setup page with three steps:

Step 1: Scan QR Code

• Open your authenticator app
• Select "Add account" or "Scan QR code"
• Point your camera at the QR code on screen
• The account will be added to your app

Step 2: Manual Entry (Alternative)

• If you can't scan the QR code, use manual entry
• In your authenticator app, select "Enter key manually"
• Enter the account name (e.g., "Admin Panel - Your Name")
• Copy and paste the secret key shown on screen
• Select "Time-based" as the type
• Save the account

Step 3: Verify Code

• Look at your authenticator app
• Enter the current 6-digit code in the verification field
• Click Enable Two-Factor Authentication

1. You'll be shown your recovery codes
2. Important: Save these recovery codes in a secure location
3. Click Print Codes or Copy Codes to save them
4. Store them in a password manager or secure location

Result: 2FA is now enabled on your account. You'll need to enter a code from your authenticator app every time you log in.

Task 2: Logging In with 2FA

1. Go to the login page
2. Enter your email and password
3. Click Login
4. You'll be redirected to the 2FA challenge page
5. Open your authenticator app
6. Find the entry for this admin panel
7. Enter the current 6-digit code
8. Click Verify

Result: You're logged into your account.

Tip: The codes change every 30 seconds. If a code doesn't work, wait for the next one.

Task 3: Viewing Recovery Codes

1. Navigate to Dashboard > Two-Factor Authentication
2. Click View Recovery Codes
3. You'll see your list of recovery codes
4. Each code can only be used once
5. Click Print Codes to print them
6. Click Copy Codes to copy them to clipboard

Result: You can see and save your recovery codes.

Important: Store recovery codes securely. Anyone with these codes can access your account.

Task 4: Using a Recovery Code

If you lose access to your authenticator app:

1. Go to the login page
2. Enter your email and password
3. On the 2FA challenge page, click Use a recovery code
4. Enter one of your recovery codes
5. Click Verify

Result: You're logged in using a recovery code.

Note: Each recovery code can only be used once. After using a code, regenerate new ones.

Task 5: Regenerating Recovery Codes

If you've used recovery codes or lost them:

1. Navigate to Dashboard > Two-Factor Authentication
2. Click View Recovery Codes
3. Scroll to the Regenerate Recovery Codes section
4. Enter your password to confirm
5. Click Regenerate Recovery Codes
6. Confirm the action in the popup
7. New recovery codes will be displayed
8. Important: Save the new codes immediately
9. Old recovery codes are now invalid

Result: You have a fresh set of recovery codes.

Task 6: Disabling Two-Factor Authentication

1. Navigate to Dashboard > Two-Factor Authentication
2. Scroll to the Disable Two-Factor Authentication section
3. Enter your password in the confirmation field
4. Click Disable Two-Factor Authentication
5. Confirm the action in the popup

Result: 2FA is disabled. You'll only need your password to log in.

Warning: Disabling 2FA makes your account less secure. Only disable if absolutely necessary.

Task 7: Setting Up 2FA on a New Device

If you get a new phone or reinstall your authenticator app:

1. Before losing access to old device:

   • View and save your recovery codes
   • Or disable and re-enable 2FA to get a new QR code

2. If you still have access to old device:

   • Disable 2FA (requires code from old device)
   • Re-enable 2FA and scan new QR code with new device

3. If you lost access to old device:

   • Use a recovery code to log in
   • Disable 2FA
   • Re-enable 2FA with new device

Result: 2FA is set up on your new device.

Task 8: Troubleshooting Invalid Codes

If your codes aren't working:

1. Check that your device's time is correct

   • Go to device settings
   • Enable automatic time/date
   • Ensure correct timezone

2. Wait for the next code

   • Codes change every 30 seconds
   • Don't enter a code that's about to expire

3. Try a recovery code

   • Use a recovery code to log in
   • Check your authenticator app setup

4. Contact an administrator

   • If you can't log in, ask an admin to disable 2FA on your account
   • Then set it up again

Settings and Options

System-Wide 2FA Settings

Administrators can configure 2FA policies in Security Settings:

• Enable 2FA: Allow users to enable 2FA (default: enabled)
• Mandatory for Admins: Require all admin users to use 2FA
• Recovery Codes Count: Number of recovery codes generated (default: 8)

See Security Settings for details.

Permissions

• Own Account: Any authenticated user can manage 2FA on their own account
• Other Accounts: Administrators with users.edit permission can disable 2FA for other users (in emergency situations)

Tips and Best Practices

Setup Best Practices

• Set up 2FA as soon as possible after creating your account
• Use a reliable authenticator app (Google Authenticator or Authy recommended)
• Complete the entire setup process, including saving recovery codes
• Test logging in with 2FA before closing your current session

Recovery Code Management

• Save recovery codes immediately after enabling 2FA
• Store codes in a secure password manager
• Keep a printed copy in a secure physical location
• Never share recovery codes with anyone
• Regenerate codes if you suspect they've been compromised
• Regenerate codes after using several of them

Device Management

• Set up 2FA on multiple devices if your authenticator app supports it (e.g., Authy)
• Keep your authenticator app backed up (if the app supports it)
• Before switching phones, ensure you have recovery codes
• Consider using a cloud-syncing authenticator like Authy

Security Considerations

• Never disable 2FA unless absolutely necessary
• Don't share your authenticator device with others
• Keep your device locked with a PIN or biometric
• Be cautious of phishing attempts asking for 2FA codes
• Never enter 2FA codes on suspicious websites

Time Synchronization

• Ensure your device's time is set automatically
• TOTP codes are time-based and require accurate time
• If codes don't work, check your device's time settings
• Use network-provided time when possible

Troubleshooting

Problem: QR Code Won't Scan

Solution:

1. Ensure good lighting and steady hands
2. Try moving the phone closer or farther from the screen
3. Increase screen brightness
4. Use the manual entry method instead
5. Try a different authenticator app
6. Take a screenshot and scan from photos (less secure)

Problem: Codes Not Working

Solution:

1. Check device time is set to automatic
2. Verify correct timezone
3. Wait for the next code (codes change every 30 seconds)
4. Ensure you're entering the code for the correct account
5. Try removing and re-adding the account in your authenticator app
6. Use a recovery code to log in and reset 2FA

Problem: Lost Access to Authenticator App

Solution:

1. Use a recovery code to log in
2. Once logged in, disable 2FA
3. Set up 2FA again with your new device
4. Generate new recovery codes

If you don't have recovery codes:

1. Contact an administrator
2. Verify your identity
3. Ask them to disable 2FA on your account
4. Set up 2FA again after logging in

Problem: Recovery Codes Not Working

Solution:

1. Ensure you're entering the code exactly as shown (no spaces)
2. Verify you haven't used this code before (each code works once)
3. Check that you're using codes from the most recent generation
4. Contact an administrator if all codes fail

Problem: Can't Disable 2FA

Solution:

1. Ensure you're entering your password correctly
2. Try using a 2FA code instead of recovery code
3. Clear browser cache and try again
4. Check browser console for errors
5. Contact an administrator for assistance

Problem: Mandatory 2FA Enforcement

Solution:
If 2FA is mandatory for admins:

1. You must set up 2FA to continue using the admin panel
2. Follow the setup process completely
3. Save your recovery codes
4. Contact your administrator if you need an exception

Problem: Multiple Failed Attempts

Solution:

1. Stop entering codes and wait a few minutes
2. Check your device's time synchronization
3. Use a recovery code instead
4. If locked out, contact an administrator
5. Your account may be temporarily locked for security

Related Modules

• Security Settings: Configure 2FA policies and requirements
• Security Events: Monitor 2FA-related security events
• Profile: Access 2FA settings from your profile
• Users: Administrators can manage user 2FA status