Last indexed: 31 January 2026 (cf9511)

Authentication Architecture

Overview

The Light framework implements a multi-layered JWT-based authentication architecture centered around the Auth\Service class. The system uses dual-token authentication (access/refresh tokens), persistent session tracking via the UserLog table, and security mechanisms including account lockout and token revocation.

Key Architectural Components:

Component	Location	Role
`Auth\Service`	src/Auth/Service.php	Core authentication service, validates JWT tokens, loads user context
`AuthController`	src/Controller/AuthController.php	GraphQL API for all authentication operations
`User` Model	src/Model/User.php	User entity with session and permission methods
`UserLog` Table	Database	Persistent session storage and audit trail
JWT Tokens	HTTP-only cookies	Access tokens (15min) and refresh tokens (7 days)
Cache Layer	Symfony Cache	Token revocation blacklist

This page focuses on the authentication architecture. For specific authentication methods, see:

Password Authentication - Username/password login with 2FA
JWT Token System - Token generation and refresh flow
Two-Factor Authentication (2FA) - TOTP setup and verification
WebAuthn (Biometric) - Passwordless authentication
OAuth and Social Login - Google, Microsoft, Facebook integration
Password Management - Reset and expiration policies

For authorization, see RBAC System.

Sources: src/App.php38-147 src/Auth/Service.php1-147 src/Controller/AuthController.php1-50

Multi-Layered Architecture

The authentication system operates across multiple architectural layers, from HTTP requests through business logic to data persistence:

Diagram: Multi-Layered Authentication Architecture

The authentication system spans four architectural layers. The HTTP layer handles token storage in cookies. The application layer creates a per-request Auth\Service instance and exposes authentication mutations via AuthController. The business logic layer validates credentials and generates tokens. The data layer persists sessions in UserLog and maintains a token revocation cache.

Sources: src/App.php500-537 src/Auth/Service.php28-80 src/Controller/AuthController.php374-456 src/Model/User.php50-227

Auth\Service - The Core Authentication Component

The Auth\Service class is instantiated for every HTTP request and serves as the central authentication component. It implements GraphQLite's AuthenticationServiceInterface and AuthorizationServiceInterface to integrate with the GraphQL security system.

Initialization and Token Validation

Diagram: Auth\Service Initialization Flow (per request)

Every request creates a new Auth\Service instance that validates the JWT token, checks for revocation, loads the user from the database, and updates session activity. The service is then injected into the DI container and registered with the GraphQL schema factory.

Sources: src/Auth/Service.php28-80 src/App.php526-535

Key Methods and Responsibilities

The Auth\Service class provides the following interface:

Method	Return Type	Purpose	Used By
`isLogged()`	`bool`	Checks if user is authenticated, throws `TokenExpiredException` if token expired	GraphQLite `#[Logged]` annotation
`getUser()`	`?User`	Returns authenticated `User` object or null	GraphQLite `#[InjectUser]` annotation
`isAllowed(string $right)`	`bool`	Checks RBAC permission via `User->isGranted()`	GraphQLite `#[Right]` annotation
`getJti()`	`?string`	Returns JWT ID for session tracking	Session management, logout
`isViewAsMode()`	`bool`	Checks if admin is impersonating another user	UI conditional logic
`getOrgUser()`	`?User`	Returns original admin user in view-as mode	Permission checks

View-As Mode Implementation: When the JWT payload contains both id (admin user) and view_as (target user), the service loads two user objects:

$this->org_user: The original administrator
$this->user: The target user being impersonated

This allows administrators to see the application as another user would see it while maintaining their admin permissions for certain operations.

Sources: src/Auth/Service.php82-147

Integration with GraphQLite

The Auth\Service is registered with the GraphQL schema factory as both the authentication and authorization service:

This enables GraphQLite's security annotations to work automatically:

#[Logged]: Calls Auth\Service::isLogged(), throws exception if false
#[InjectUser]: Calls Auth\Service::getUser(), injects result as parameter
#[Right("permission")]: Calls Auth\Service::isAllowed("permission"), checks RBAC

Sources: src/App.php526-535 src/Auth/Service.php100-147

JWT Token System

The framework uses a dual-token architecture with access tokens for API authentication and refresh tokens for obtaining new access tokens without re-authentication.

Token Structure and Lifecycle

Token Type	Default Lifetime	Purpose	Cookie Path	Claims
`access_token`	900s (15 min)	GraphQL API authentication	`/`	`iss`, `jti`, `iat`, `exp`, `role`, `id`, `type`, `view_as?`
`refresh_token`	604800s (7 days)	Obtaining new access tokens	`/refresh_token`	`iss`, `jti`, `iat`, `exp`, `id`, `type`

Shared Claims:

iss: Issuer, always "light server"
jti: JWT ID (UUID v4), uniquely identifies the session
iat: Issued at timestamp
exp: Expiration timestamp
id: User ID (references User.user_id)
type: Token type discriminator

Access Token Specific:

role: Always "Users" (legacy field)
view_as: Optional, present when admin impersonates another user

Both tokens share the same jti value, linking them to a single session record in the UserLog table. This enables session-wide revocation - revoking the jti invalidates both the access and refresh tokens.

Sources: src/App.php636-685 src/Auth/Service.php28-80

Token Generation Process

Token generation occurs in App::userLogin() after successful authentication:

Diagram: Token Generation in App::userLogin()

The App::userLogin() method generates both tokens with a shared jti, creates a session record in UserLog, and sets both cookies. The access token cookie is available site-wide (/), while the refresh token cookie is restricted to the refresh endpoint (/refresh_token) for security.

Sources: src/App.php631-685

Token Refresh Flow

The refresh token enables obtaining a new access token without re-authentication:

Diagram: Token Refresh Flow

The /refresh_token endpoint validates the refresh token, verifies the user still exists, and generates a new access token with the same jti. This maintains session continuity while limiting access token lifetime for security.

Sources: src/App.php877-920

Token Revocation Mechanism

Token revocation is implemented using a cache-based blacklist. When a user logs out or a session is terminated:

Diagram: Token Revocation on Logout

The logout process adds the jti to cache with a TTL equal to the refresh token lifetime, updates the UserLog record with logout_dt, and clears both token cookies.

Revocation Check: Every request validates tokens against the cache in Auth\Service:

This approach provides immediate token invalidation without requiring database queries on every request.

Sources: src/Controller/AuthController.php334-370 src/Auth/Service.php58-60

Session Tracking via UserLog

The UserLog table provides persistent session storage, audit trails, and session management capabilities.

UserLog Schema and Lifecycle

Diagram: UserLog Schema

Each UserLog record represents one authentication attempt or session. The jti field links JWT tokens to database records. The result field distinguishes successful logins ("SUCCESS") from failed attempts ("FAIL"). Active sessions have logout_dt = NULL.

Session Lifecycle:

Login: UserLog record created with login_dt, result="SUCCESS", jti from token
Active: last_access_time updated on each API request via User->saveLastAccessTime()
Logout: logout_dt set to current timestamp
Expired: Sessions older than access_token_expire are considered inactive

Sources: src/App.php650-657 src/Auth/Service.php75-80 src/Controller/AuthController.php343-347

Session Management Methods

The User model provides GraphQL-queryable session management:

getSessions(): array - Lists all active sessions for the user:

The method filters for successful logins with no logout_dt within the token expiration window. It marks the current session (is_current = true) based on matching jti.

revokeSession(jti): bool - Terminates a specific session:

This sets logout_dt for the specified session, preventing it from appearing in active session lists.

saveLastAccessTime(jti): void - Updates last activity timestamp:

Called by Auth\Service on every authenticated request to track session activity.

Sources: src/Model/User.php50-82 src/Model/User.php201-204

Failed Login Tracking

Failed authentication attempts are also recorded in UserLog with result="FAIL":

Failed login records do not have a jti since no token is generated. These records are used by the account lockout mechanism.

Sources: src/Controller/AuthController.php408-415

Account Lockout Mechanism

The framework protects against brute-force password attacks using IP-based account lockout after repeated failed login attempts.

Configuration

Lockout behavior is controlled by two configuration values in the Config table:

Key	Type	Default	Purpose
`auth_lockout_attempts`	int	5	Number of failed attempts before lockout
`auth_lockout_duration`	int	15	Lockout window in minutes

Implementation

The lockout check occurs before password verification in AuthController::login():

The User::isAuthLocked() method implements the lockout logic:

Diagram: Account Lockout Decision Flow

The method queries UserLog for failed attempts from the same IP within the lockout window. If the failure count meets or exceeds the threshold, the account is locked for that IP address.

Key Implementation Details:

Important Characteristics:

IP-based: Lockout applies per IP address, not globally
Time-windowed: Only considers failures within the lockout duration
Self-healing: Lockout automatically expires after the duration window passes
No database flag: Lockout is computed on-demand from UserLog records

Sources: src/Model/User.php206-227 src/Controller/AuthController.php403-405

Additional Security Features

Password Expiration

Password expiration forces users to periodically change their passwords:

Configuration:

password_expiration: Enable/disable (boolean)
password_expiration_duration: Days until password expires (default: 90)

Enforcement: During login, if enabled and password_dt exceeds the duration, login fails with "password is expired". Users must call changeExpiredPassword() to update.

Sources: src/Controller/AuthController.php446-452 src/Controller/AuthController.php64-102

Rate Limiting on 2FA Setup

The 2FA setup process is rate-limited to prevent abuse:

This limits users to 5 setup attempts per 10 minutes per username.

Sources: src/Controller/AuthController.php31-39

Configuration Reference

Authentication behavior is controlled by configuration values in the Config table and environment variables:

Config Table Values

Key	Type	Default	Purpose
`access_token_expire`	int	900	Access token lifetime (seconds)
`refresh_token_expire`	int	604800	Refresh token lifetime (seconds)
`two_factor_authentication`	bool	false	Enforce 2FA for all users
`auth_lockout_attempts`	int	5	Failed attempts before lockout
`auth_lockout_duration`	int	15	Lockout duration (minutes)
`password_expiration`	bool	false	Enable password expiration
`password_expiration_duration`	int	90	Password lifetime (days)
`authentication_google_client_id`	string	-	Google OAuth client ID
`authentication_microsoft_client_id`	string	-	Microsoft OAuth client ID
`authentication_facebook_app_id`	string	-	Facebook OAuth app ID

Environment Variables

Variable	Required	Purpose
`JWT_SECRET`	Yes	Secret key for JWT signing
`COOKIE_DOMAIN`	No	Cookie domain (default: current domain)
`COOKIE_SECURE`	No	Require HTTPS for cookies (default: false)
`COOKIE_SAMESITE`	No	SameSite cookie attribute (default: "Lax")
`COOKIE_PARTITIONED`	No	Enable partitioned cookies (default: false)

Sources: src/App.php602-685 src/Controller/AuthController.php

Configuration

Authentication behavior is controlled by several configuration values stored in the Config model:

Configuration Key	Type	Default	Purpose
`access_token_expire`	int	900 (15 min)	Access token lifetime in seconds
`refresh_token_expire`	int	604800 (7 days)	Refresh token lifetime in seconds
`two_factor_authentication`	bool	false	Enforce 2FA for all users
`auth_lockout_attempts`	int	5	Failed attempts before lockout
`auth_lockout_duration`	int	15	Lockout duration in minutes
`password_expiration`	bool	false	Enable password expiration
`password_expiration_duration`	int	90	Password lifetime in days
`authentication_google_client_id`	string	-	Google OAuth client ID
`authentication_microsoft_client_id`	string	-	Microsoft OAuth client ID
`authentication_facebook_app_id`	string	-	Facebook OAuth app ID

Additionally, the .env file must contain:

JWT_SECRET: Secret key for JWT signing (required)
COOKIE_DOMAIN, COOKIE_SECURE, COOKIE_SAMESITE: Cookie configuration

Sources: src/Controller/AuthController.php src/Auth/Service.php

Refresh this wiki

URL: https://deepwiki.com/mathsgod/light/5.1-authentication-architecture