Authentication System

The authentication system verifies user identities in Hyperf applications through a factory pattern that manages different authentication strategies. The system is built around three core components: the AuthManager factory, authentication guards, and user providers.

This page provides an overview of the authentication subsystem architecture and flow. For detailed information about specific components:

• AuthManager - Factory pattern and guard management
• User Resolver - User resolution mechanism
• Guards - Guard implementations (Session, JWT, Request)
• User Providers - User data retrieval abstractions

For authorization and access control, see Authorization System. For HTTP middleware integration, see Middleware.

Core Components

The authentication system consists of three primary layers that work together to verify user identities:

Component Architecture

Sources: src/AuthManager.php22-255 src/Guards/SessionGuard.php15-149 src/Guards/JwtGuard.php19-203 src/Guards/RequestGuard.php16-75

Component Responsibilities

Component	File	Responsibility
AuthManager	src/AuthManager.php	Factory for creating and managing guards
SessionGuard	src/Guards/SessionGuard.php	Stateful authentication using sessions
JwtGuard	src/Guards/JwtGuard.php	Stateless authentication using JWT tokens
RequestGuard	src/Guards/RequestGuard.php	Custom callback-based authentication
GuardHelpers	src/Guards/GuardHelpers.php	Shared guard functionality trait
EloquentUserProvider	src/Providers/EloquentUserProvider.php	User retrieval via Eloquent ORM
DatabaseUserProvider	src/Providers/DatabaseUserProvider.php	User retrieval via Query Builder
CreatesUserProviders	src/CreatesUserProviders.php	User provider factory trait

Sources: src/AuthManager.php1-255 src/Guards/SessionGuard.php1-149 src/Guards/JwtGuard.php1-203 src/Guards/RequestGuard.php1-75

Authentication Flow

The authentication process follows a consistent flow regardless of the guard type used:

Request Authentication Flow

Sources: src/Guards/JwtGuard.php98-122 src/Guards/SessionGuard.php103-126 src/AuthManager.php60-65

Login Flow

Sources: src/Guards/JwtGuard.php36-49 src/Guards/SessionGuard.php30-43

Guard Types

The authentication system provides three guard implementations, each designed for different authentication scenarios:

Guard Comparison

Sources: src/Guards/SessionGuard.php15-149 src/Guards/JwtGuard.php19-203 src/Guards/RequestGuard.php16-75

Guard Feature Matrix

Feature	SessionGuard	JwtGuard	RequestGuard
State Management	Stateful	Stateless	Stateless
Storage Location	Server-side session	Client-side token	Custom callback
Authentication Method	Session cookie	JWT in Authorization header	Developer-defined
Token Expiration	Session lifetime	TTL in token (exp claim)	Callback-dependent
Token Refresh	Session regeneration	refresh() method	Callback-dependent
Typical Use Case	Traditional web apps	REST APIs	Custom auth schemes
Implementation File	src/Guards/SessionGuard.php	src/Guards/JwtGuard.php	src/Guards/RequestGuard.php

Sources: src/Guards/SessionGuard.php1-149 src/Guards/JwtGuard.php1-203 src/Guards/RequestGuard.php1-75

Common Guard Interface

All guards implement common methods through the GuardHelpers trait:

Method	Return Type	Description
user()	?Authenticatable	Retrieves authenticated user
check()	bool	Determines if user is authenticated
guest()	bool	Determines if user is not authenticated
id()	int|string|null	Gets user identifier
validate()	bool	Validates credentials without login
authenticate()	Authenticatable	Gets user or throws exception
hasUser()	bool	Checks if user is loaded
setUser()	void	Manually sets authenticated user

Sources: src/Guards/GuardHelpers.php1-115

For detailed documentation on each guard type, see Guards.

User Providers

User providers abstract user data retrieval from various storage mechanisms. Guards use providers to load user data during authentication.

Provider Architecture

Sources: src/AuthManager.php24 src/Guards/SessionGuard.php20-24 src/Guards/JwtGuard.php24-30 src/Guards/RequestGuard.php31-38

Provider Methods

The UserProvider contract defines methods for user retrieval and credential validation:

Method	Parameters	Return Type	Purpose
retrieveById()	mixed $identifier	?Authenticatable	Retrieves user by primary key
retrieveByToken()	mixed $identifier, string $token	?Authenticatable	Retrieves user by remember token
retrieveByCredentials()	array $credentials	?Authenticatable	Retrieves user by login credentials
validateCredentials()	Authenticatable $user, array $credentials	bool	Validates user's password
updateRememberToken()	Authenticatable $user, string $token	void	Updates remember token

The AuthManager creates providers via the CreatesUserProviders trait based on configuration. For detailed provider implementations, see User Providers.

Sources: src/AuthManager.php24

Context and User Resolution

The authentication system integrates with Hyperf's context system to provide per-request authentication state and user resolution. The AuthManager maintains user resolvers that can be customized for different authentication scenarios.

Sources: src/AuthManager.php52-55 src/AuthManager.php166-175 src/AuthManager.php212-217 src/AuthManager.php251-254

The context system enables:

• Per-request guard selection: Different routes can use different authentication guards
• Dynamic user resolution: Custom logic for determining the authenticated user
• Request-scoped defaults: Authentication state that persists throughout a request lifecycle

For detailed information about specific guard implementations, see Guards. For user provider implementations, see User Providers. For the central factory management, see AuthManager.