APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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

Email

  • 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:

  1. The matching code is removed from the in-memory recovery-code list.
  2. The remaining list is written back to the user document.
  3. The authentication workflow persists the modified user document.
  4. 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.

Next Steps

Previous

Passwords & Authentication Sessions

Explore Passwords & Authentication Sessions

Next

TOTP & Email Providers

Explore TOTP & Email Providers