TwoFactorAuth

Manages two-factor authentication (2FA) methods for enhanced account security. This entity stores configuration for various 2FA methods like SMS codes, authenticator apps (Google Authenticator, Authy), email codes, or hardware keys. Each user can have multiple 2FA methods configured, with one marked as primary. When 2FA is enabled, users must provide both their password and a second factor to log in. This dramatically increases account security by requiring something the user knows (password) and something they have (phone, hardware key). The entity tracks verification status, failed attempts, and can temporarily lock 2FA after too many failures to prevent brute force attacks.

21 properties

Schema

Properties

Property	Type	Mode	Description	Required
twoFactorAuthId	uuid	stored	Unique identifier for this 2FA configuration	Required
userId	uuid	stored	The user who owns this 2FA method	Required
method	string	enum	Type of 2FA method being used Values: `totp, sms, email, authenticator, hardware_key, biometric, backup_codes` Example: `"totp"`	Required
isEnabled	boolean	stored	Whether this 2FA method is currently active	Optional
isPrimary	boolean	stored	Whether this is the default 2FA method	Optional
secretHash	string	stored	Encrypted secret key for TOTP generation	Optional
phoneNumber	string	stored	Phone number for SMS-based 2FA	Optional
email	string	stored	Email address for email-based 2FA	Optional
deviceName	string	stored	Friendly name for hardware key or authenticator app	Optional
deviceSerial	string	stored	Serial number of hardware security key	Optional
algorithm	string	enum	Cryptographic algorithm for TOTP Values: `SHA1, SHA256, SHA512`	Optional
digits	integer	stored	Number of digits in the generated code	Optional
period	integer	stored	Time period in seconds for TOTP code rotation	Optional
verifiedAt	DateTime	stored	When this 2FA method was verified and confirmed working	Optional
lastUsedAt	DateTime	stored	Last successful use of this 2FA method	Optional
failedAttempts	integer	stored	Count of consecutive failed verification attempts	Optional
lockedUntil	DateTime	stored	Temporary lock after too many failed attempts	Optional
backupCodesGenerated	integer	stored	Total number of backup codes created	Optional
backupCodesRemaining	integer	stored	How many unused backup codes are left	Optional
createdAt	DateTime	stored	When this 2FA method was added	Required
updatedAt	DateTime	stored	Last modification timestamp	Optional

Examples

Example 1

{
  "@type": "TwoFactorAuth",
  "twoFactorAuthId": "2fa_auth123",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "totp",
  "isEnabled": true,
  "isPrimary": true,
  "deviceName": "Google Authenticator on iPhone",
  "algorithm": "SHA256",
  "digits": 6,
  "period": 30,
  "verifiedAt": "2024-01-15T10:00:00Z",
  "lastUsedAt": "2024-03-15T14:30:00Z",
  "failedAttempts": 0,
  "backupCodesGenerated": 10,
  "backupCodesRemaining": 8,
  "createdAt": "2024-01-15T10:00:00Z"
}

Example 2

{
  "@type": "TwoFactorAuth",
  "twoFactorAuthId": "2fa_sms456",
  "userId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "method": "sms",
  "isEnabled": true,
  "isPrimary": false,
  "phoneNumber": "+1-555-123-4567",
  "verifiedAt": "2024-01-20T11:00:00Z",
  "lastUsedAt": "2024-03-10T09:15:00Z",
  "failedAttempts": 2,
  "backupCodesGenerated": 0,
  "backupCodesRemaining": 0,
  "createdAt": "2024-01-20T11:00:00Z"
}