Skip to main content

Two-Factor Authentication (2FA)

Enhanced Security with Time-Based One-Time Passwords​

OmniCRM supports two-factor authentication (2FA) using time-based one-time passwords (TOTP). This adds an extra layer of security by requiring users to provide both their password and a time-sensitive code from an authenticator app.

See also: RBAC for 2FA management permissions, Authentication Flows for login process details.

Purpose​

2FA provides:

  1. Enhanced Security --- Protects accounts even if passwords are compromised.
  2. Compliance --- Meets security requirements for regulated industries.
  3. User Choice --- Optional for users, can be enforced per role or globally.
  4. Industry Standard --- Uses TOTP protocol compatible with Google Authenticator, Authy, Microsoft Authenticator, and other standard apps.

How 2FA Works​

When 2FA is enabled for a user:

  1. Setup --- User scans a QR code with their authenticator app during enrollment.
  2. Login --- After entering username/password, user provides the 6-digit code from their app.
  3. Verification --- System validates the time-based code matches the expected value.
  4. Access --- User gains access only after both factors are verified.

Enabling 2FA​

For Individual Users​

Users can enable 2FA for their own account:

  1. Navigate to User Settings or Profile
  2. Select Enable Two-Factor Authentication
  3. Scan the QR code with an authenticator app
  4. Enter the verification code to confirm setup
  5. Save backup codes in a secure location

Backup & Recovery​

Backup Codes​

When enabling 2FA, users receive backup codes that can be used if their device is unavailable:

  • Each code is single-use
  • Store codes securely offline
  • Generate new codes if all are used

Admin Reset​

If a user loses access to their authenticator and all backup codes are exhausted, an administrator with database access can manually reset the user's 2FA by clearing the totp_secret field in the database. The user can then re-enable 2FA.

API Integration​

Enable 2FA for a user​

POST /2fa/enable/user/{user_id}

{
  "password": "current_password"
}

Response includes provisioning URI (for QR code) and backup codes.

Verify 2FA setup​

POST /2fa/verify-setup/user/{user_id}

{
  "code": "123456"
}

Verify 2FA during login​

POST /2fa/verify/user/{user_id}

{
  "code": "123456"
}

Returns access token, refresh token, and user data upon successful verification.

Regenerate backup codes​

POST /2fa/backup-codes/regenerate/user/{user_id}

Requires authentication. Returns new set of backup codes.

Best Practices​

  • Backup codes first. Always save backup codes before completing 2FA setup.
  • Educate users. Provide clear instructions for setup and recovery.
  • Secure reset process. Verify user identity before manually resetting 2FA in the database.

FAQ​

What authenticator apps are supported? Any TOTP-compatible app (Google Authenticator, Authy, Microsoft Authenticator, 1Password, etc.).

What if I lose my phone? Use a backup code or contact an administrator to reset 2FA.

Can I use SMS instead of an app? Currently, only TOTP authenticator apps are supported.

Is 2FA required? It depends on your organization's policy. 2FA is typically required for administrative and support staff roles but is optional for customer users. The system does not enforce 2FA for customer accounts (customer role users do not see 2FA enrollment prompts).

How long are TOTP codes valid? Codes refresh every 30 seconds and have a small time window for validation (typically accepts codes from current 30-second window plus previous/next windows for clock skew tolerance).