Authentication Methods

Purpose and Scope

This document provides a high-level overview of the five authentication methods supported by the Light framework and how they integrate with the authentication system. Each method is implemented in the AuthController class and results in JWT token issuance through App::userLogin().

For detailed implementation information, see the dedicated pages for each method:

• Password Authentication - Username/password login with bcrypt hashing
• JWT Token System - Token generation, validation, and session management
• Two-Factor Authentication (2FA) - TOTP-based second factor
• WebAuthn (Biometric) - Passwordless biometric authentication
• OAuth and Social Login - Google, Microsoft, and Facebook integration
• Password Management - Password reset and change operations

For authentication flow and session handling, see Authentication Architecture. For authorization enforcement, see RBAC System.

Authentication Methods Summary

The Light framework implements five authentication methods through the AuthController class. All methods ultimately invoke App::userLogin(User $user) to generate JWT tokens and establish sessions tracked in the UserLog table:

Method	GraphQL Mutations	User Model Field	Primary Purpose
Password	login(username, password, code?)	username, password	Traditional username/password authentication
JWT Tokens	logout(), implicit in cookies	Session via UserLog.jti	Session persistence and transport mechanism
Two-Factor (2FA)	updateMy2FA(secret, code), getMy2FA()	secret	TOTP-based second factor authentication
WebAuthn	(external implementation)	credential	Passwordless biometric/hardware key authentication
OAuth Social	lightAuthLogin{Google|Microsoft|Facebook}	google, microsoft, facebook	Third-party OAuth provider authentication

All authentication methods can be combined with 2FA when enabled globally via Config::Value("authentication_2fa_required") or per-user via User.secret.

Sources: src/Controller/AuthController.php1-636

Authentication Architecture Overview

The following diagram illustrates how authentication methods are processed through the AuthController and converge to the App::userLogin() method:

All authentication paths converge at App::userLogin(), which generates JWT access and refresh tokens, logs the session to UserLog, and sets secure HTTP-only cookies.

Sources: src/Controller/AuthController.php374-456 src/Controller/AuthController.php304-330 src/Controller/AuthController.php238-267 src/Controller/AuthController.php271-300

Multi-Factor Authentication Flow

This diagram shows how 2FA is enforced across different authentication methods:

When User.secret is set, 2FA is mandatory for that user. When global config authentication_2fa_required is enabled, all users must set up 2FA before authentication succeeds.

Sources: src/Controller/AuthController.php420-443 src/Controller/AuthController.php430-443

GraphQL API Endpoints

The AuthController exposes these GraphQL mutations for authentication operations:

Primary Authentication Mutations

Mutation	Parameters	Returns	Line Reference
login	username, password, code?	bool	374-456
lightAuthLoginGoogle	credential	bool	304-330
lightAuthLoginMicrosoft	access_token	bool	238-267
lightAuthLoginFacebook	access_token	bool	271-300
logout	(uses Auth\Service)	bool	334-370

Account Linking Mutations

Mutation	Parameters	Returns	Requires Auth	Line Reference
lightAuthRegisterGoogle	credential	bool	Yes (#[Logged])	206-234
lightAuthRegisterMicrosoft	account_id	bool	Yes (#[Logged])	190-201
lightAuthRegisterFacebook	access_token	bool	Yes (#[Logged])	123-150
lightAuthUnlinkGoogle	(none)	bool	Yes (#[Logged])	175-183
lightAuthUnlinkMicrosoft	(none)	bool	Yes (#[Logged])	164-172
lightAuthUnlinkFacebook	(none)	bool	Yes (#[Logged])	153-161

Two-Factor Authentication Mutations

Mutation	Parameters	Returns	Requires Auth	Line Reference
getMy2FA	(none)	{secret, host, image}	Yes (#[Logged])	516-530
updateMy2FA	secret, code	bool	Yes (#[Logged])	499-508
updateTwoFactorAuthentication	username, password, secret, code	bool	No	31-61
reset2FA	id	bool	Yes (#[Right('user.reset2fa')])	108-118

Password Management Mutations

Mutation	Parameters	Returns	Line Reference
forgetPassword	username, email	string (JWT)	598-635
forgetPasswordVerifyCode	jwt, code	bool	533-552
resetPassword	jwt, password, code	bool	555-594
changeExpiredPassword	username, old_password, new_password	bool	64-102

Sources: src/Controller/AuthController.php1-636

User Model Storage Integration

The User model stores authentication credentials and identifiers in dedicated columns:

Each authentication method queries the User table using method-specific fields. Account linking mutations (e.g., lightAuthRegisterGoogle) update these fields while authenticated.

Sources: src/Controller/AuthController.php398-456 src/Controller/AuthController.php257-267 src/Controller/AuthController.php289-300 src/Controller/AuthController.php322-330

Account Linking System

Users can link multiple authentication methods to a single account through the registration mutations. The linking process enforces one-to-one relationships between OAuth provider IDs and user accounts:

Linking Enforcement Rules

1. One Provider ID per Account: When linking a provider, the system first clears that provider ID from any existing user account at src/Controller/AuthController.php138-141 (Facebook), 193-196 (Microsoft), 225-228 (Google).

2. Requires Authentication: All lightAuthRegister* mutations require #[Logged] annotation, meaning the user must be authenticated via another method before linking.

3. Unlinking Support: Users can unlink providers via lightAuthUnlink* mutations without affecting other authentication methods.

Example Scenario: A user authenticated via password can link their Google account by calling lightAuthRegisterGoogle(credential). Subsequently, they can log in using either login(username, password) or lightAuthLoginGoogle(credential).

Sources: src/Controller/AuthController.php123-150 src/Controller/AuthController.php190-201 src/Controller/AuthController.php206-234

Configuration Requirements

Authentication methods require configuration values stored in the Config model or environment variables:

Core Authentication Configuration

Config Key	Type	Default	Purpose	Retrieved Via
password_expiration	bool	false	Enable password expiration	Config::Value("password_expiration")
password_expiration_duration	int	90	Days until password expires	Config::Value("password_expiration_duration", 90)
authentication_2fa_required	bool	false	Global 2FA enforcement	App::isTwoFactorAuthentication()
auth_lockout_duration	int	15	Account lockout duration (minutes)	Config::Value("auth_lockout_duration", 15)
JWT_SECRET	string	(required)	JWT signing key	$_ENV['JWT_SECRET']

OAuth Provider Configuration

Config Key	Type	Required By	Line Reference
authentication_google_client_id	string	loginGoogle, registerGoogle	212 310
authentication_microsoft_client_id	string	loginMicrosoft	240
authentication_facebook_app_id	string	loginFacebook	274

Password Reset Configuration

Config Key	Type	Default	Purpose	Line Reference
forget_password_email_subject	string	"Password Reset Code"	Email subject line	611
forget_password_email_template	string	"Your password reset code is: {code}"	Email body template	612

Sources: src/Controller/AuthController.php73-82 src/Controller/AuthController.php212-214 src/Controller/AuthController.php240-242 src/Controller/AuthController.php274-275 src/Controller/AuthController.php611-613

Security Features Summary

The authentication system implements multiple layers of security across all methods:

Password Security

• Bcrypt hashing with PASSWORD_DEFAULT algorithm
• Legacy hash rejection for old SHA-256/SHA-512 hashes at 458-465
• Password expiration enforcement via password_dt field at 446-452
• Account lockout via User::isAuthLocked() at 403-405

Session Security

• Failed login tracking in UserLog.result='FAIL' at 409-416
• JWT token blacklisting on logout via cache at 338-339
• HttpOnly cookies to prevent XSS attacks at 350-367
• Session logging with JTI, IP, and user agent tracking

2FA Security

• Rate limiting (5 attempts per 10 minutes) for code setup at 34-39
• Rate limiting (5 attempts per 10 minutes) for password reset at 542-549
• TOTP RFC 6238 standard implementation
• QR code generation for easy mobile setup at 523-529

OAuth Security

• Provider token verification against official APIs
• One-to-one provider mapping enforcement at 138-141 193-196 225-228
• Account unlinking prevents unauthorized takeover

WebAuthn Security

• FIDO2 cryptographic verification
• Hardware-backed credentials
• Biometric authentication support

For detailed security implementation of each method, see the dedicated pages for Password Authentication, JWT Token System, Two-Factor Authentication, WebAuthn, and OAuth/Social Login.

Sources: src/Controller/AuthController.php34-39 src/Controller/AuthController.php334-370 src/Controller/AuthController.php403-416 src/Controller/AuthController.php446-465

Session Establishment

All authentication methods converge to establish sessions through the same flow:

The App::userLogin() method generates JWT tokens with unique JTI (JWT ID) values that are:

• Stored in UserLog to track active sessions
• Used for token revocation during logout at 338-347
• Included in JWT payload for validation by Auth\Service

Sources: src/Controller/AuthController.php454-456 src/Controller/AuthController.php262-263 src/Controller/AuthController.php295-296 src/Controller/AuthController.php327-328

Detailed Documentation

For in-depth documentation of each authentication method, refer to the following pages:

• Password Authentication - Password hashing, validation, and expiration
• JWT Token System - Token generation, validation, and blacklisting
• WebAuthn and FIDO2 - Biometric and hardware key authentication
• Social Authentication - OAuth integration with Google, Microsoft, and Facebook
• Two-Factor Authentication - TOTP setup and verification