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

Force Sign In

A complete, reusable authentication gateway for protected APPNETOS application content.

Purpose

Force Sign In protects an application's content chain. It checks the current authentication state before protected content is rendered. Authenticated users continue into the application without seeing a sign-in page; unauthenticated users receive the complete sign-in interface instead.

The Core App provides credential handling, pending two-factor workflows, TOTP enrollment and verification, email-code verification and resend handling, optional remembered devices, localized templates, and the required frontend resources. Credential and two-factor verification are delegated to the shared APPNETOS authentication layer.

Placement in the content chain

1. Force Sign In
Check authentication
2. Decision
Authenticated?
3. Result
Continue content or render sign-in

Authenticated: __invoke() returns an empty string and the remaining content chain continues. Not authenticated: Force Sign In renders its sign-in or pending two-factor view and terminates normal response processing, so later content is not rendered.

Authentication and two-factor options

The shared authentication system supports conventional sign-in as well as TOTP and email-based two-factor challenges. The active authentication configuration and user state determine which verification steps are required.

  • Without 2FA: standard credential-based sign-in.
  • TOTP: authenticator-app codes, including initial enrollment and QR-code provisioning.
  • Email 2FA: a verification code delivered by the shared authentication and mailer infrastructure; a working mailer configuration is required.
  • Trusted devices: optional device persistence through a dedicated collection, with an overridable lifetime.

Providing a trusted-device collection does not by itself enable or select a two-factor provider. Returning null from that collection hook disables remembered-device persistence without disabling ordinary 2FA.

Integrating Force Sign In

Create a context-specific controller that extends CoreApp\Security\ForceSignIn, provide the correct user collection, and customize its presentation as needed. Add the controller as an early content App in the protected application's content configuration.

The APPNETOS DNS Control admin context provides a concrete example:

namespace AppnetosDnsControl\Admin;

use Core\Collection\AdminUserCollection;
use Core\Collection\User\AdminTwoFactorDeviceCollection;
use Core\Collection\User\TwoFactorDeviceCollection\Base as BaseTwoFactorDeviceCollection;
use Core\Collection\UserCollection\Base as BaseUserCollection;
use Core\Registry;
use CoreApp\Security\ForceSignIn as CoreAppForceSignIn;

class ForceSignIn extends CoreAppForceSignIn
{
    protected function getUserCollection(): BaseUserCollection|null
    {
        return Registry::get(AdminUserCollection::class);
    }

    protected function getTwoFactorDeviceCollection(): BaseTwoFactorDeviceCollection|null
    {
        return Registry::get(AdminTwoFactorDeviceCollection::class);
    }

    protected function getLogo(): string
    {
        return '/src/appnetos-dns-control/admin/img/icon-500.png';
    }
}

The example illustrates controller inheritance and collection mapping. The actual content-chain placement is configured separately in the hosting application.

Override methods

Override these protected methods in your application-specific subclass. Most projects need only the user collection and a few branding methods; the authentication workflow itself is inherited.

Method Type Purpose
getUserCollection(): BaseUserCollection|null Required Selects the context-specific user collection used for credential verification. A missing or invalid collection prevents initialization.
getTwoFactorDeviceCollection(): BaseTwoFactorDeviceCollection|null Optional Provides persistence for remembered or trusted two-factor devices. Returning null disables trusted-device persistence, not normal two-factor authentication.
getResetPasswordUriId(): ObjectId|string|null Optional Supplies the URI document ID for an optional password-reset link. Null omits the link.
getAuthenticationLifetime(): int Optional Trusted-device lifetime in seconds; default is 2,592,000 seconds (30 days).
getTotpIssuer(): string Optional Issuer label used for TOTP enrollment; default APPNETOS.
getFavicon(): string Presentation Favicon for the authentication page.
getLogo(): string Presentation Logo shown in the authentication interface.
getBackgroundImageUrl(): string|null Presentation Optional authentication-page background image URL.
getApplicationName(): string|null Presentation Display name used by the authentication interface.
getSignInTemplate(): string Templates Twig template for the credential form.
getTotpTemplate(): string Templates Twig template for TOTP code verification.
getTotpSetupTemplate(): string Templates Twig template for initial TOTP setup.
getEmailTemplate(): string Templates Twig template for email code verification.

Additional internal template and rendering helpers exist in the base class. They are not required for typical integration and should only be customized when the inherited presentation flow must change.

What you get out of the box

Rather than implementing an authentication interface and its associated state transitions from scratch, applications reuse a maintained Core App and focus on their own user collection, authentication configuration, branding and protected business functionality.

One integration. A complete sign-in experience. The same foundation can be reused across multiple APPNETOS applications and contexts without duplicating the authentication UI.

Implementation Details

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

Overview

CoreApp\Security\ForceSignIn is the reusable APPNETOS authentication UI and URI-enforcement Core App.

It is intended to be placed at the beginning of an application/content chain for protected URIs.

Basic Behavior

User authenticated?
 ├── yes
 │    ↓
 │  render nothing
 │  continue remaining content chain
 │
 └── no
      ↓
    render authentication UI
      ↓
    stop remaining response processing

ForceSignIn does not implement authentication mechanisms itself.

Authentication remains in:

Core\User\Auth

Features

ForceSignIn supports:

  • Sign-in form
  • Credential validation
  • Failed credential feedback
  • TOTP verification
  • Initial TOTP enrollment
  • QR-code display
  • Email two-factor authentication
  • Email resend
  • Email delivery errors
  • Trusted-device selection
  • Optional password-reset link
  • Application-specific logo
  • Application-specific background
  • Application display name
  • Translation integration
  • Shared JavaScript and CSS

Application Child

A concrete application/context child typically supplies only the application-specific dependencies and presentation values.

Typical hooks:

protected function getUserCollection(): BaseUserCollection|null;

protected function getTwoFactorDeviceCollection(): BaseTwoFactorDeviceCollection|null;

protected function getResetPasswordUriId(): ObjectId|string|null;

protected function getAuthenticationLifetime(): int;

protected function getApplicationName(): string|null;

protected function getLogo(): string;

protected function getBackgroundImageUrl(): string|null;

User Collection

The application must provide the mapped user collection required by the authentication workflow.

Returning no collection makes ForceSignIn unavailable for that application/context.

Trusted Devices

Trusted-device persistence is optional.

Returning null from:

getTwoFactorDeviceCollection()

disables trusted-device functionality only.

TOTP and email 2FA remain available.

Password Reset Link

ForceSignIn can optionally render a password-reset link.

The application child provides a URI ID:

protected function getResetPasswordUriId(): ObjectId|string|null
{
    return '...';
}

The Base resolves the URI through Core\Uri.

If the child returns null, no password-reset link is rendered.

The Twig layer receives the final URL only:

{% if url_list.forgot_password %}
    <a href="{{ url_list.forgot_password }}">
        {{ translations.core_app__security__force_sign_in__forgot_password }}
    </a>
{% endif %}

The template does not need to know anything about URI IDs or Core\Uri.

TOTP Flow

Pending provider = TOTP
      ↓
Persisted secret exists?
 ├── yes → code input
 └── no
      ↓
   startTotpSetup()
      ↓
   QR code + secret
      ↓
   first code
      ↓
   completeTotpSetup()

Email Flow

Pending provider = email
      ↓
Email provider available?
 ├── no → error only
 └── yes
      ↓
   startEmailChallenge()
      ↓
   challenge ready?
    ├── no → delivery error + resend
    └── yes
         ↓
      code input
         ↓
      verifyEmail()

Email UI States

Mailer unavailable

error shown
no code input
no authenticate button
no resend

Send failed

error shown
no code input
resend available

Challenge ready

code input
remember-device checkbox
authenticate button
resend available

Shared OTP JavaScript

TOTP and email use the same six-digit input controller.

The JavaScript combines the six input fields into:

input[name="code"]

Provider-specific behavior is limited to:

verifyTotp()
verifyEmail()

Enter activates the currently rendered authentication button, so the shared OTP input logic remains provider-neutral.

Reusability

A new APPNETOS admin application does not need to implement its own authentication UI or 2FA workflow.

Once the application's user mappings and ForceSignIn child exist, the application inherits the complete shared flow:

Login
→ Session
→ Password
→ TOTP
→ TOTP Setup
→ Email 2FA
→ Trusted Device
→ Password Reset link
→ AJAX UI

This is one of the central reusable Core App patterns in APPNETOS.

Next Steps

Previous

Security

Explore Security

Next

Session Indicator Line

Explore Session Indicator Line