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

User & Authentication

Optional, context-isolated users, groups and authentication services.

Optional Identity Services

APPNETOS separates the always-loaded shared core from application-specific identity storage. User and group services are optional: an application can run without users, groups or permissions. The appnetos-docs application is an example of a runtime that does not map either collection.

Context & Collection Mapping

Context-specific class mapping keeps app and admin user and group collections isolated.
Context-specific class mapping keeps app and admin user and group collections isolated.
Context / mapping Users Groups
app AppUserCollection AppGroupCollection
admin AdminUserCollection AdminGroupCollection
No user collection Unavailable No users or groups
User collection only Available No group-based permissions

Concrete documents inherit shared base properties and declare their persistence collection with #[Database(collection: ...)]. Class mapping resolves context-specific implementations. Admin collections are not accessible through the app context by default.

Identity Components

The user controller exposes the current user document; the group controller evaluates permissions; authentication manages credentials, 2FA and trusted devices. Core session storage is documented separately from authentication session state.

Standard Authentication Flow

The reusable CoreApp\Security\ForceSignIn app delegates credential and second-factor checks to Core\User\Auth. A successful login redirects, so the next request restores the authenticated user and loads active groups.

Implementation Details

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

APPNETOS User Core

Overview

The APPNETOS User Core provides the shared runtime user, group, permission and authentication infrastructure used by APPNETOS applications and contexts.

The system is intentionally split into small reusable Core controllers. Application- and context-specific behavior is supplied through APPNETOS class mapping, while the shared Core owns the generic workflow.

The User Core covers:

  • Runtime user state
  • User collection integration
  • Group and permission handling
  • Password authentication
  • Authentication sessions
  • Two-factor authentication
  • TOTP authentication and enrollment
  • Email two-factor authentication
  • Recovery codes
  • Trusted devices
  • Authentication lifecycle hooks
  • Force Sign In integration

Architecture

Core\User
├── Base
├── Group
│   └── Base
└── Auth
    ├── Base
    ├── Password
    │   └── Base
    ├── Session
    │   └── Base
    ├── TrustedDevice
    │   └── Base
    └── TwoFactor
        ├── Base
        └── Provider
            ├── Base
            ├── Totp
            │   └── Base
            └── Email
                └── Base

The UI integration for protected application areas is provided by the reusable Core App:

CoreApp\Security\ForceSignIn

Design Principle

Shared Core
→ owns reusable behavior

Mapped child
→ supplies application/context-specific dependencies

Application
→ configures and uses the shared implementation

Applications without user management can leave the corresponding mapped collections unavailable. The User Core is designed to remain optional.

Documentation Structure

User

Authentication

Two-Factor Authentication

Core Apps

Authentication Overview

Purpose

Core\User\Auth\Base is the central APPNETOS authentication workflow controller.

It coordinates specialized controllers instead of implementing authentication mechanisms directly.

Architecture

Core\User\Auth
├── Password
├── Session
├── TwoFactor
└── TrustedDevice

Responsibility split:

Auth
→ orchestrates authentication

Password
→ hashing and password verification

Session
→ authentication session state

TwoFactor
→ provider coordination

TrustedDevice
→ persistent trusted-browser/device handling

Authentication Flow

The authentication controller coordinates:

  • User lookup
  • Password verification
  • Failed-login tracking
  • Successful-login tracking
  • Two-factor requirement detection
  • Trusted-device validation
  • TOTP authentication
  • TOTP enrollment
  • Email authentication challenges
  • Recovery-code verification
  • Runtime user assignment
  • Logout
  • Authentication lifecycle hooks

Optional Infrastructure

Authentication depends on the user collection mapped for the current runtime context.

If no user collection is available, users cannot be resolved and authentication is effectively unavailable.

Trusted devices are optional and independent from two-factor authentication itself.

User collection
→ basic authentication capability

Two-factor provider configured on user
→ interactive 2FA capability

TwoFactorDevice collection
→ trusted-device capability

A missing trusted-device collection must never disable TOTP or email two-factor authentication.

Complete Authentication

A successful password check is not always a complete authentication.

When 2FA is required:

password verified
→ authentication session pending
→ runtime user not authenticated

Only after successful second-factor verification:

2FA successful
→ authentication session complete
→ runtime user assigned

Next Steps

User Management

Explore User Management

Groups & Permissions

Explore Groups & Permissions

Authentication

Explore Authentication

Passwords & Authentication Sessions

Explore Passwords & Authentication Sessions

Two-Factor Authentication

Explore Two-Factor Authentication

TOTP & Email Providers

Explore TOTP & Email Providers

Trusted Devices

Explore Trusted Devices