Password Authentication

This page documents the username/password authentication mechanism in the Light framework, including credential verification, brute force protection through account lockout, and password expiration handling. For information about JWT token generation following successful authentication, see JWT Token System. For password reset and change operations, see Password Management.

---

Overview

Password authentication is implemented through the login mutation in AuthController. The system verifies user credentials, enforces security policies including brute force protection and password expiration, and optionally validates two-factor authentication codes before issuing JWT tokens.

Sources: src/Controller/AuthController.php374-456

---

Login Flow

The following diagram illustrates the complete password authentication flow from credential submission to successful login:

Sources: src/Controller/AuthController.php374-456 src/Model/User.php206-227

---

Password Verification

Standard Password Verification

Password verification is handled by the private PasswordVerify method, which delegates to PHP's password_verify function for bcrypt/argon2 hash validation:

Implementation Details:

Aspect	Implementation
Method	AuthController::PasswordVerify(string $password, string $hash)
Location	src/Controller/AuthController.php458-465
Algorithm	PHP password_verify() - supports bcrypt, argon2i, argon2id
Legacy Detection	Rejects SHA-256 ($5) and SHA-512 ($6) crypt hashes

Sources: src/Controller/AuthController.php458-465

Legacy Hash Handling

The system explicitly rejects legacy password hashes created with SHA-256 ($5) or SHA-512 ($6) crypt algorithms. When detected, the authentication fails with an error message directing users to contact administrators for password reset:

This prevents security vulnerabilities from outdated hashing algorithms while providing clear user guidance.

Sources: src/Controller/AuthController.php460-463

---

Brute Force Protection

Account Lockout Mechanism

The system implements IP-based account lockout to prevent brute force attacks. Failed login attempts are tracked in the UserLog table, and accounts are locked when the failure threshold is exceeded within the lockout duration window:

Configuration Parameters:

Parameter	Default	Purpose	Config Key
Lockout Duration	15 minutes	Time window for counting failures	auth_lockout_duration
Lockout Attempts	5 attempts	Failure threshold before lockout	auth_lockout_attempts

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

Failed Login Logging

Every failed authentication attempt is immediately logged to the UserLog table before the error is returned:

This logging enables:

• IP-based lockout tracking: Recent failures from the same IP are counted
• Audit trail: All authentication attempts are recorded with timestamps
• Security monitoring: Failed attempts can be analyzed for attack patterns

Sources: src/Controller/AuthController.php407-418

---

Password Expiration Integration

When password expiration is enabled via Config.password_expiration, the login flow validates that the user's password has not exceeded the configured duration:

Password Date Tracking:

Field	Type	Purpose
User.password_dt	datetime	Timestamp when password was last set
Updated during	Password creation, password change, password reset

When a password is expired, users must use the changeExpiredPassword mutation to set a new password. See Password Management for details.

Sources: src/Controller/AuthController.php446-452

---

First User Creation

The login method includes special logic to create the initial administrator account when no users exist in the system:

Default First User Properties:

Property	Value
username	From login attempt
first_name	"Admin"
email	"admin@localhost"
password	Bcrypt hash of provided password
join_date	Current date
status	0 (active)
language	"en"
password_dt	Current timestamp
role	"Administrators"

Sources: src/Controller/AuthController.php378-394

---

Two-Factor Authentication Integration

When a user has two-factor authentication enabled (i.e., User.secret is set), the login flow requires a valid TOTP code:

Additionally, when system-wide 2FA is mandated via App.isTwoFactorAuthentication(), users without User.secret configured are blocked with error setup_2fa_required:

Sources: src/Controller/AuthController.php420-443

---

Successful Login

Upon successful authentication and all policy checks, the login flow calls App.userLogin(user) which:

1. Generates JWT Tokens: Creates access and refresh tokens (see JWT Token System)
2. Sets HTTP Cookies: Stores tokens in secure, HTTP-only cookies
3. Creates Session Log: Inserts UserLog entry with result='SUCCESS', jti, IP, and user agent
4. Returns Success: The mutation returns true

UserLog Entry Structure:

Field	Value
user_id	Authenticated user ID
jti	JWT token ID (for revocation)
login_dt	Current timestamp
result	"SUCCESS"
ip	Client IP address ($_SERVER['REMOTE_ADDR'])
user_agent	Client user agent string
logout_dt	NULL (set during logout)
last_access_time	Updated on each request

Sources: src/Controller/AuthController.php454-456

---

Code Entity Reference

Primary Classes and Methods

Entity	Location	Purpose
AuthController::login()	src/Controller/AuthController.php374-456	Main login mutation handler
AuthController::PasswordVerify()	src/Controller/AuthController.php458-465	Password verification with legacy detection
User::isAuthLocked()	src/Model/User.php206-227	Brute force protection check
App::userLogin()	Referenced in AuthController	JWT generation and session creation

Database Tables

Table	Purpose	Key Fields
User	User accounts	username, password, password_dt, secret, status
UserLog	Authentication attempts	user_id, ip, login_dt, result, jti
UserRole	Role assignments	user_id, role
Config	System configuration	auth_lockout_duration, auth_lockout_attempts, password_expiration

GraphQL API

Mutation	Parameters	Returns	Description
login	username: String! password: String! code: String	Boolean!	Authenticate user and issue JWT tokens
changeExpiredPassword	username: String! old_password: String! new_password: String!	Boolean!	Change expired password

Sources: src/Controller/AuthController.php374-456 src/Controller/AuthController.php64-102