Skip to main content

MFA / Two-Factor Authentication

O.D.I.N. supports TOTP-based (Time-based One-Time Password) two-factor authentication for all user accounts.

Available on Every Tier

MFA is included in every license tier, including Community.

Overview​

When MFA is enabled on an account, login requires:

  1. Username and password (first screen)
  2. A 6-digit TOTP code from an authenticator app (second screen)

TOTP is compatible with any standard authenticator app, including:

  • Google Authenticator
  • Authy
  • Bitwarden Authenticator
  • 1Password (built-in TOTP)
  • iOS/macOS built-in Passwords app

Enabling MFA (User Self-Service)​

  1. Log in and go to Settings → Account → Security
  2. Click Enable Two-Factor Authentication
  3. Scan the QR code with your authenticator app
  4. Enter the 6-digit code shown in your app to confirm setup
  5. Save your backup codes — displayed once on the confirmation screen
Store Backup Codes Securely

Backup codes are displayed only once during setup. Store them in a secure location (password manager, printed and locked away). If you lose access to your authenticator app and do not have backup codes, only an admin can restore access to your account.

Login with MFA​

When logging in to an MFA-enabled account:

  1. Enter username and password on the first screen → click Sign In
  2. A second screen prompts for the 6-digit TOTP code
  3. Open your authenticator app, find the O.D.I.N. entry, and enter the current code
  4. Click Verify to complete login

TOTP codes refresh every 30 seconds. If the code expires while you are typing, wait for the next one.

Admin MFA Management​

Admins can reset (force-disable) MFA for any user from the user management table. Admins cannot force-enable MFA for another user; each user enrolls from their own account.

Reset MFA (Account Lockout Recovery)​

If a user is locked out (for example, a lost phone):

  1. Go to Settings → Access → Users & Groups
  2. Click the Reset MFA (shield) button in the user's row; it is shown only for users with MFA enabled
  3. Confirm with Disable MFA
  4. The user can log in with password only and optionally re-enroll MFA

The mfa_enabled and mfa_secret columns are stored per user in the users table. Disabling MFA clears the secret.

Recovery Options​

SituationRecovery Method
Lost authenticator app, have backup codesUse a backup code at the TOTP prompt
Lost authenticator app, no backup codesAsk an admin to disable MFA for your account
Admin locked out of MFAUse another admin account, or access via the database directly (emergency only)

MFA Security Notes​

  • MFA pending tokens are blacklisted immediately after use to prevent session duplication (v1.3.63)
  • Password change revokes all existing sessions, requiring re-authentication including the MFA step (v1.3.66)
  • MFA is enforced at the login endpoint level — API clients using scoped tokens or the system API key bypass MFA (tokens are not session-based)

See Also​