TwoFactorConfig

Configuration for two-factor authentication (2FA) methods associated with a user account. This entity enables multi-factor authentication by supporting various verification methods including TOTP (Time-based One-Time Password), SMS, email codes, authenticator apps, and backup codes. It allows users to configure multiple 2FA methods for redundancy, tracks enrollment status, stores encrypted secrets, and manages backup recovery codes. The entity supports modern authentication standards like TOTP (RFC 6238), WebAuthn, and hardware security keys, providing flexible and secure second-factor authentication across web applications, mobile apps, and enterprise systems.

11 properties

Schema

Properties

Property	Type	Mode	Description	Required
user	User	stored	Reference to the User who owns this 2FA configuration - 2FA is shared across all tenants for this user	Required
method	string	stored	The two-factor authentication method type Values: `totp, sms, email, authenticator, webauthn, backup-codes` Example: `"totp"`	Required
isEnabled	boolean	stored	Whether this 2FA method is currently enabled and active Example: `true`	Required
isPrimary	boolean	stored	Whether this is the primary/default 2FA method for the user Example: `true`	Optional
configuration	json	stored	Method-specific configuration data (structure varies by method type: TOTP={secret}, SMS={phoneNumber}, email={emailAddress}, WebAuthn={publicKeyCredential}, backup-codes={codes})	Required
deviceName	string	stored	User-friendly name for the device or authenticator app (for identification in UI) Example: `"iPhone 13 - Google Authenticator"`	Optional
enrolledAt	datetime	stored	Date/time when this 2FA method was enrolled/configured Example: `"2024-01-15T10:30:00Z"`	Optional
lastUsedAt	datetime	stored	Date/time when this 2FA method was last successfully used Example: `"2024-11-22T08:15:00Z"`	Optional
verifiedAt	datetime	stored	Date/time when this 2FA method was verified during enrollment Example: `"2024-01-15T10:35:00Z"`	Optional
daysSinceLastUse	number	calculated	Number of days since this method was last used for authentication	Optional
isVerified	boolean	calculated	Whether this 2FA method has been verified and is ready for use	Optional

Examples

Example 1

{
  "@type": "TwoFactorConfig",
  "user": {
    "@type": "User",
    "username": "john.doe"
  },
  "method": "totp",
  "isEnabled": true,
  "isPrimary": true,
  "configuration": {
    "algorithm": "SHA1",
    "digits": 6,
    "period": 30
  },
  "deviceName": "Google Authenticator",
  "enrolledAt": "2024-01-15T10:30:00Z",
  "verifiedAt": "2024-01-15T10:35:00Z",
  "lastUsedAt": "2024-11-22T08:15:00Z"
}

Example 2

{
  "@type": "TwoFactorConfig",
  "user": {
    "@type": "User",
    "username": "jane.smith"
  },
  "method": "sms",
  "isEnabled": true,
  "isPrimary": true,
  "configuration": {
    "phoneNumber": "+33612345678",
    "phoneNumberVerified": true
  },
  "deviceName": "Personal Mobile",
  "enrolledAt": "2024-03-20T14:00:00Z",
  "verifiedAt": "2024-03-20T14:05:00Z",
  "lastUsedAt": "2024-11-20T09:30:00Z"
}

Example 3

{
  "@type": "TwoFactorConfig",
  "user": {
    "@type": "User",
    "username": "alice.brown"
  },
  "method": "backup-codes",
  "isEnabled": true,
  "isPrimary": false,
  "configuration": {
    "totalCodes": 10,
    "usedCodes": 2,
    "remainingCodes": 8
  },
  "enrolledAt": "2024-01-15T10:30:00Z",
  "verifiedAt": "2024-01-15T10:30:00Z"
}

Example 4

{
  "@type": "TwoFactorConfig",
  "user": {
    "@type": "User",
    "username": "bob.wilson"
  },
  "method": "webauthn",
  "isEnabled": true,
  "isPrimary": true,
  "configuration": {
    "credentialId": "AaFdkcKS-RZmTLH_c...",
    "credentialType": "public-key",
    "transports": [
      "usb",
      "nfc"
    ]
  },
  "deviceName": "YubiKey 5 NFC",
  "enrolledAt": "2024-06-10T16:20:00Z",
  "verifiedAt": "2024-06-10T16:22:00Z",
  "lastUsedAt": "2024-11-21T11:45:00Z"
}

Example 5

{
  "@type": "TwoFactorConfig",
  "user": {
    "@type": "User",
    "username": "john.doe"
  },
  "method": "authenticator",
  "isEnabled": true,
  "isPrimary": false,
  "configuration": {
    "algorithm": "SHA256",
    "digits": 6,
    "period": 30
  },
  "deviceName": "Authy - iPhone",
  "enrolledAt": "2024-02-01T09:00:00Z",
  "verifiedAt": "2024-02-01T09:05:00Z",
  "lastUsedAt": "2024-11-15T14:20:00Z"
}