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
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.