Two-Factor Authentication
Second-factor verification, enrollment and recovery.
Supported Factors
APPNETOS supports time-based one-time passwords (TOTP) and email verification codes. The user document controls whether 2FA is enabled and which providers are configured. The authentication controller handles pending challenges and successful completion.
Enrollment & Recovery
TOTP enrollment creates a temporary secret and provisioning QR code. The secret is persisted to the user only after successful code verification. Recovery codes are hashed and intended for single use. Trusted-device support is optional and does not replace the 2FA configuration.
When a custom login workflow supports 2FA, it must call Auth::login() with its third
argument enabled.
Public API Reference
Core\User\Auth\TwoFactor
Class & Registry
Class:
Core\User\Auth\TwoFactor
Extends:
Core\User\Auth\TwoFactor\Base
use Core\User\Auth\TwoFactor;
use Core\Registry;
$twoFactor = Registry::get(TwoFactor::class);
| Method | Description |
|---|---|
public function init(): void |
Initialize two-factor authentication controller |
public function isRequired(UserDocument $userDocument): bool |
Check if two-factor authentication is required |
public function getProvider(UserDocument $userDocument): string|null
|
Get primary two-factor authentication provider |
public function verify( UserDocument $userDocument, string $code ):
bool
|
Verify two-factor authentication code |
public function generateTotpSecret(): string|null |
Generate TOTP secret |
public function verifyTotpSecret( string $secret, string $code ): bool
|
Verify TOTP code by secret |
public function getTotpProvisioningUriBySecret( string $secret, string
$issuer,
string
$account ): string|null |
Get TOTP provisioning URI by secret |
public function getTotpQrCodeBySecret( string $secret, string $issuer, string
$account
): string|null |
Get TOTP QR code by secret |
public function getTotpProvisioningUri( UserDocument $userDocument, string
$issuer,
string|null $account = null ): string|null |
Get TOTP provisioning URI |
public function getTotpQrCode( UserDocument $userDocument, string $issuer,
string|null
$account = null ): string|null |
Get TOTP QR code |
public function getEmailAvailable(): bool |
Check email two-factor authentication availability |
public function generateEmailCode(): string|null |
Generate email two-factor authentication code |
public function hashEmailCode(string $code): string |
Hash email two-factor authentication code |
public function verifyEmailCode( string $code, string $hash ): bool
|
Verify email two-factor authentication code |
public function sendEmailCode( UserDocument $userDocument, string $code ):
bool
|
Send email two-factor authentication code |
public function getEmailCodeLifetime(): int |
Get email two-factor authentication code lifetime |
public function hashRecoveryCode(string $code): string |
Hash recovery code |
Implementation Details
The following technical reference expands the existing guide with authentication lifecycle, state management, and provider behavior.
Two-Factor Authentication Overview
Overview
Core\User\Auth\TwoFactor\Base coordinates shared APPNETOS two-factor authentication
providers.
Supported shared provider identifiers are:
totp
email
Recovery codes are handled as a fallback verification mechanism.
User Configuration
2FA is required only when:
user.twoFactorEnabled = true
AND
at least one supported provider exists
Provider values are normalized before comparison.
The first supported provider in the stored provider list becomes the primary provider.
Example:
[
"totp",
"email"
]
Primary provider:
totp
Important Security Rule
Provider infrastructure availability must not silently disable configured 2FA.
Example:
user requires email 2FA
mailer unavailable
Result:
authentication remains pending
technical error is displayed
The login must not be completed without the configured second factor.
Provider Responsibilities
TOTP
- Secret generation
- RFC6238 verification
- Provisioning URI
- QR code generation
- Initial enrollment support
- Mailer availability
- Secure numeric code generation
- HMAC hashing
- Code verification
- Code delivery
- Challenge lifetime
Recovery Codes
- Hashed persistent recovery codes
- Single-use verification
Responsibility Boundary
TwoFactor controller
→ provider coordination
Provider
→ mechanism-specific behavior
Auth Session
→ temporary challenge state
Auth controller
→ workflow orchestration
ForceSignIn
→ UI and HTTP integration
Recovery Codes
Overview
APPNETOS supports recovery codes as a fallback two-factor verification mechanism.
Recovery codes are stored as password hashes on the user document.
Storage
Each recovery code is persisted using:
password_hash(
$code,
PASSWORD_DEFAULT,
);
The clear recovery code is not stored.
Verification
Verification iterates over persisted hashes and uses:
password_verify()
Single-Use Behavior
When a recovery code is successfully verified:
- The matching code is removed from the in-memory recovery-code list.
- The remaining list is written back to the user document.
- The authentication workflow persists the modified user document.
- Authentication continues.
A successfully used recovery code cannot be reused.
Responsibility
Recovery-code verification belongs to the shared TwoFactor controller.
Management UI, generation UI and replacement workflows may be implemented separately by applications or Core Apps.