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

Authentication

Credential validation, ForceSignIn and the standard redirect workflow.

Standard Sign-In Workflow

ForceSignIn validates credentials, handles optional two-factor verification and redirects after successful authentication.
ForceSignIn validates credentials, handles optional two-factor verification and redirects after successful authentication.

ForceSignIn is placed at the beginning of a protected content chain. If a user is already authenticated, rendering continues. Otherwise it displays sign-in or the pending 2FA view. Credential verification is delegated to Core\User\Auth.

The standard ForceSignIn::signIn() explicitly calls Auth::login($email, $password, true), enabling second-factor handling. Custom login implementations must deliberately pass true when 2FA is supported.

Completion & Redirect

If the user does not require 2FA, the login completes and the frontend receives a redirect action. If 2FA is required, the session remains pending until a valid TOTP or email code is provided, or an eligible trusted device is validated. The successful redirect begins a new request and loads the user and active groups.

The ForceSignIn CoreApp is a reusable presentation and HTTP workflow. Its protected template and collection hooks are extension points, not public API methods.

ForceSignIn Public Endpoints

The public AJAX handlers are annotated for unauthenticated requests and return render or redirect actions.

ForceSignIn (5 methods)

Public method signature Description
public function __invoke(): ViewSlot|string|null Invoke ForceSignIn
public function signIn(): void Public API operation.
public function verifyTotp(): void Public API operation.
public function verifyEmail(): void Public API operation.
public function resendEmailCode(): void Public API operation.

Public API Reference

Core\User\Auth

Class & Registry

Class: Core\User\Auth

Extends: Core\User\Auth\Base

use Core\User\Auth;
use Core\Registry;

$auth = Registry::get(Auth::class);
Method Description
public function init(): void Initialize authentication controller
public function setTwoFactorDeviceCollection(TwoFactorDeviceCollection|null $collection): void Set two-factor device collection
public function login(string $login, string $password, bool $twoFactorAvailable = false): bool Login
public function logout(): void Logout
public function hasUser(): bool Check if authenticated user exists
public function isAuthenticated(): bool Check if user is authenticated
public function isTwoFactorPending(): bool Check if two-factor authentication is pending
public function getPendingUser(): UserDocument|null Get pending two-factor authentication user
public function getPendingTwoFactorProvider(): string|null Get pending two-factor authentication provider
public function completeTwoFactor( string $code, bool $rememberDevice = false, int $trustedDeviceLifetime = 2592000 ): bool Complete two-factor authentication
public function startTotpSetup(string $issuer, string|null $account = null): array|null Start TOTP two-factor authentication setup
public function completeTotpSetup( string $code, bool $rememberDevice = false, int $trustedDeviceLifetime = 2592000 ): bool Complete TOTP two-factor authentication setup
public function getEmailTwoFactorAvailable(): bool Get email two-factor authentication availability
public function startEmailChallenge(bool $force = false): bool Start email two-factor authentication challenge
public function completeEmailTwoFactor( string $code, bool $rememberDevice = false, int $trustedDeviceLifetime = 2592000 ): bool Complete email two-factor authentication

Implementation Details

The following technical reference expands the existing guide with authentication lifecycle, state management, and provider behavior.

Authentication Flow

Complete Flow

Request protected URI
        ↓
Force Sign In
        ↓
Already authenticated?
 ├── yes
 │    ↓
 │  continue application/content chain
 │
 └── no
      ↓
    Sign-in form
      ↓
    Resolve active user
      ↓
    User exists?
     ├── no  → authentication failed
     └── yes
           ↓
        Verify password
           ↓
        Password valid?
         ├── no
         │    ↓
         │  failed-login handling
         │
         └── yes
              ↓
           afterPasswordVerified()
              ↓
           Is 2FA required?
            ├── no
            │    ↓
            │  authenticated session
            │    ↓
            │  runtime user
            │    ↓
            │  afterLogin()
            │
            └── yes
                 ↓
              Trusted device available?
                 ↓
              Trusted device valid?
               ├── yes
               │    ↓
               │  authenticated session
               │    ↓
               │  runtime user
               │
               └── no
                    ↓
                 pending 2FA session
                    ↓
                 Primary provider
                 ├── TOTP
                 │    ├── initialized
                 │    │      ↓
                 │    │   code input
                 │    │
                 │    └── not initialized
                 │           ↓
                 │       temporary secret
                 │           ↓
                 │       QR enrollment
                 │           ↓
                 │       first valid code
                 │           ↓
                 │       persist secret
                 │
                 └── Email
                      ↓
                   mailer available?
                    ├── no → technical error
                    └── yes
                          ↓
                       generate challenge
                          ↓
                       send code
                          ↓
                       code input
                    ↓
                 2FA successful
                    ↓
                 optional trusted device
                    ↓
                 authentication session complete
                    ↓
                 runtime user assigned
                    ↓
                 afterLogin()
                    ↓
                 redirect / continue

Failed Login

When no user exists, authentication returns false.

When the user exists but password verification fails:

afterFailedLogin()
→ increaseFailedLoginAttempts()
→ persist user

Password Success

After successful password verification:

afterPasswordVerified()
→ markLogin()
→ persist user

This occurs before the two-factor decision.

Two-Factor Decision

2FA is required only when:

two-factor infrastructure enabled for login flow
AND
user has 2FA enabled
AND
at least one supported provider is configured

Provider infrastructure availability is not used to silently bypass configured 2FA.

For example, when email 2FA is configured but the mailer is unavailable, authentication remains pending and the user receives an error.

Trusted Device

A valid trusted device is evaluated after password verification and before interactive 2FA.

2FA required
→ trusted-device cookie
→ token hash lookup
→ user + token + expiration valid?

When valid, interactive 2FA is skipped.

Finalization

All successful second-factor flows use the same finalization behavior:

optional trusted-device creation
→ complete authentication session
→ assign runtime user
→ afterLogin()

Authentication Lifecycle Hooks

Overview

Core\User\Auth\Base provides lifecycle hooks for application- or context-specific authentication behavior.

afterPasswordVerified()

protected function afterPasswordVerified(
    UserDocument $document,
): void

Executed after successful password verification and before the final two-factor decision.

The shared implementation currently:

markLogin()
→ persist user document

afterFailedLogin()

protected function afterFailedLogin(
    UserDocument|null $document,
): void

Executed after a failed authentication attempt.

When the user document could be resolved, the shared implementation:

increaseFailedLoginAttempts()
→ persist user document

When no user could be resolved, no persistent document is modified.

afterLogin()

protected function afterLogin(
    UserDocument $document,
): void

Executed only after authentication is fully completed.

This means:

No 2FA required
→ after password authentication

2FA required
→ after successful second-factor verification

It is not executed while authentication is still pending.

beforeLogout()

protected function beforeLogout(
    UserDocument $document,
): void

Executed before the runtime user and authentication session are cleared.

afterLogout()

protected function afterLogout(
    UserDocument $document,
): void

Executed after logout completes.

Usage

Lifecycle hooks allow mapped authentication child controllers to add application-specific behavior without duplicating the shared authentication flow.

Authentication Class Mapping

Overview

APPNETOS authentication uses class mapping to separate shared Core behavior from application- and context-specific dependencies.

Shared Base classes define reusable behavior.

Mapped child classes provide runtime-specific collections, configuration or integration.

Registry Usage

Applications resolve mapped Core controllers:

Registry::get(Core\User::class);
Registry::get(Core\User\Auth::class);
Registry::get(Core\User\Auth\Session::class);
Registry::get(Core\User\Auth\Password::class);
Registry::get(Core\User\Auth\TwoFactor::class);

Shared Base classes should not be resolved directly.

User Collection Mapping

Core\User\Base defines:

protected function getCollection(): UserCollection|null
{
    return null;
}

The mapped child supplies the application/context-specific user collection.

Group Collection Mapping

Core\User\Group\Base follows the same pattern:

protected function getCollection(): GroupCollection|null
{
    return null;
}

Email Provider Mapping

The shared email provider never decides whether app or admin mailer settings are used.

The shared provider exposes hooks:

protected function getMailer(): array|null
{
    return null;
}

protected function getMailerUsable(): bool
{
    return false;
}

The mapped runtime child supplies the correct configuration.

Conceptually:

Email Provider Base
        ↓
Mapped Child
        ├── app context   → app mailer configuration
        └── admin context → admin mailer configuration

Design Rule

Shared Base classes should not infer runtime context when that decision can be supplied by a mapped child.

This keeps the shared Core reusable and prevents context-specific branching from spreading through the architecture.

Next Steps

Previous

Groups & Permissions

Explore Groups & Permissions

Next

Passwords & Authentication Sessions

Explore Passwords & Authentication Sessions