Two-Factor Authentication (2FA)¶

Two-Factor Authentication setup and usage guide.

Overview¶

Faraday supports Two-Factor Authentication (2FA) using TOTP (Time-based One-Time Password, RFC 6238). When enabled, users must provide both their password and a time-based code from an authenticator app to log in.

Key Characteristics¶

Supported Authenticator Apps¶

Any TOTP-compatible authenticator app works with Faraday. Tested applications include:

Enabling 2FA¶

Step 1: Navigate to Account Settings¶

1. Log in to the Faraday web interface.
2. Click the user menu (top-right corner of the screen).
3. Select Preference
4. Click the Account section on the left panel.

Step 2: Enable 2FA¶

1. Toggle the 2FA switch to enable.
2. Faraday displays a QR code containing your TOTP secret.

Step 3: Scan the QR Code¶

1. Open your authenticator app.
2. Tap Add account (or the + button).
3. Select Scan QR code.
4. Point your device camera at the QR code displayed by Faraday.
5. The authenticator app registers the account and begins generating 6-digit codes.

Step 4: Confirm Enrollment¶

1. Enter the current 6-digit code from your authenticator app into Faraday.
2. Faraday verifies the code and activates 2FA for your account.

Logging In with 2FA¶

Once 2FA is enabled, the login process requires two steps:

1. Enter credentials — Type your username and password as usual.
2. Enter TOTP code — Faraday prompts for the 6-digit code from your authenticator app. Enter the current code to complete sign-in.

Disabling 2FA¶

1. Log in to Faraday (you will need your current authenticator code).
2. Navigate to Account section into Preference Menu.
3. Toggle the 2FA switch to disable.

2FA States¶

Faraday tracks 2FA enrollment using three internal states:

Data Model¶

2FA uses the following fields on the User model:

The TOTP secret is generated server-side using the PyOTP library and stored in the faraday_user database table.

Time Synchronization Requirement¶

Verifying Time Synchronization¶

On the Faraday server:

# Check current time and NTP sync status
timedatectl status

If NTP is not active:

# Enable NTP synchronization
sudo timedatectl set-ntp true

On mobile devices: - Android: Settings > System > Date & Time > enable "Use network-provided time"

• iOS: Settings > General > Date & Time > enable "Set Automatically"

Troubleshooting¶

TOTP codes are always rejected¶

Locked out of account (lost authenticator)¶

If a user loses access to their authenticator device, an administrator can reset their 2FA via direct database access:

-- Run on the Faraday PostgreSQL database
UPDATE faraday_user
SET state_otp = 'disabled', otp_secret = NULL
WHERE username = 'locked_out_user';

After resetting, the user can log in with password only and re-enable 2FA.

2FA enrollment shows "requested" but never completes¶

The user started enrollment but did not confirm with a valid code:

1. The user should navigate back to Preference > Account > Two Factor Authentication.
2. Re-scan the QR code and enter a valid TOTP code to complete enrollment.
3. If the QR code is no longer displayed, an admin can reset the state (see above) and the user can restart enrollment.

Security Recommendations¶

1. Encourage all users to enable 2FA — Especially administrators and pentester-role users with access to sensitive vulnerability data.
2. Use an authenticator with backup — Apps like Authy support cloud backup of TOTP secrets, reducing the risk of lockout.
3. Keep server time synchronized — Ensure NTP is enabled on the Faraday server to prevent authentication failures.
4. Document the recovery process — Ensure your team knows how to reset 2FA for locked-out users via the database.

Related Documentation¶

• LDAP authentication configuration
• SAML 2.0 Single Sign-On configuration
• Server settings reference