Session Management

Purpose and Scope

This document details the session management system in Maho, which has been modernized to utilize Symfony HttpFoundation for session handling while maintaining the legacy Maho/Magento model interface. It covers session storage (Files and Redis), validation logic, security options, and the implementation of customer and admin sessions. For authentication mechanisms, see Security and Authentication.

Session Architecture Overview

Maho's session architecture bridges the legacy Mage_Core_Model_Session_Abstract interface with a Symfony-based backend. This provides a robust foundation for session storage and lifecycle management. The system uses a shared Symfony Session instance stored in the Maho registry to ensure consistency across different session namespaces (e.g., frontend, adminhtml).

Code-to-Entity Mapping

The following diagram associates natural language concepts with specific code entities in the Maho session system.

Sources:

• Mage_Core_Model_Session_Abstract definition: app/code/core/Mage/Core/Model/Session/Abstract.php31-33
• Symfony Session usage: app/code/core/Mage/Core/Model/Session/Abstract.php93-96

Session Storage Configuration

Maho supports two primary session storage handlers: Native Files and Redis. The selection is determined by the global/session_save configuration node app/code/core/Mage/Core/Model/Session/Abstract.php46

Storage Initialization Flow

The createSessionHandler() method determines the appropriate handler based on the configuration value returned by getSessionSaveMethod().

Redis Storage

Maho uses the RedisSessionHandler from Symfony app/code/core/Mage/Core/Model/Session/Abstract.php17 It requires a DSN configured in global/redis_session/dsn (e.g., redis://[password@]host[:port][/database]) app/code/core/Mage/Core/Model/Session/Abstract.php147-150 If the DSN is missing, the system throws an exception during initialization. The handler is initialized using RedisAdapter::createConnection($dsn) app/code/core/Mage/Core/Model/Session/Abstract.php159

File Storage

Uses NativeFileSessionHandler app/code/core/Mage/Core/Model/Session/Abstract.php16 pointing to the path defined in global/session_save_path app/code/core/Mage/Core/Model/Session/Abstract.php47 or the default system temporary directory.

Session Cleanup

Maho includes a cron job core_session_clean to purge expired sessions app/code/core/Mage/Core/Model/Session.php75

• Redis: Cleanup is handled automatically by Redis TTL.
• Files: The _cleanFileSystemSessions() method iterates through the session directory and unlinks files older than the configured maxIdleTime app/code/core/Mage/Core/Model/Session.php86-121 The system uses file modification time (getMTime) to determine expiration app/code/core/Mage/Core/Model/Session.php133

Sources:

• Storage selection logic: app/code/core/Mage/Core/Model/Session/Abstract.php128-135
• Redis initialization: app/code/core/Mage/Core/Model/Session/Abstract.php140-161
• File storage initialization: app/code/core/Mage/Core/Model/Session/Abstract.php163-167
• Cleanup logic: app/code/core/Mage/Core/Model/Session.php75-139

Session Models and Hierarchy

All session models inherit from Mage_Core_Model_Session_Abstract, which wraps the Symfony session object. This abstraction allows Maho to manage messages, validation data, and specific domain logic.

Class	Role	Namespace
Mage_Core_Model_Session_Abstract	Base logic, Symfony integration, and validation.	N/A
Mage_Core_Model_Session	Generic core session and form key management.	core
Mage_Admin_Model_Session	Admin user authentication and ACL.	admin
Mage_Customer_Model_Session	Frontend customer state and persistence.	customer
Mage_Api_Model_Session	API session management.	api

Sources:

• Mage_Core_Model_Session_Abstract: app/code/core/Mage/Core/Model/Session/Abstract.php31
• Mage_Core_Model_Session: app/code/core/Mage/Core/Model/Session.php24
• Mage_Admin_Model_Session: app/code/core/Mage/Admin/Model/Session.php36
• Mage_Customer_Model_Session: app/code/core/Mage/Customer/Model/Session.php50
• Mage_Api_Model_Session: app/code/core/Mage/Api/Model/Session.php19

Session Validation and Security

Maho performs validation on every session start to prevent hijacking.

Validation Criteria

Security settings are managed via configuration paths defined in the abstract model app/code/core/Mage/Core/Model/Session/Abstract.php49-53:

1. User Agent: Compares HTTP_USER_AGENT. Can be skipped via global/session/validation/http_user_agent_skip app/code/core/Mage/Core/Model/Session/Abstract.php55
2. Remote Address: Validates client IP if web/session/use_remote_addr is enabled app/code/core/Mage/Core/Model/Session/Abstract.php49
3. X-Forwarded-For: Validates forwarding headers if web/session/use_http_x_forwarded_for is set app/code/core/Mage/Core/Model/Session/Abstract.php51

Form Key Protection

The Mage_Core_Model_Session class provides getFormKey() and validateFormKey($formKey) to prevent CSRF attacks app/code/core/Mage/Core/Model/Session.php40-65 A 16-character random string is generated and stored in the session app/code/core/Mage/Core/Model/Session.php53

Sources:

• Validation constants: app/code/core/Mage/Core/Model/Session/Abstract.php49-57
• Form Key logic: app/code/core/Mage/Core/Model/Session.php40-65

Customer Sessions

The Mage_Customer_Model_Session manages the logged-in customer state. It determines its namespace based on the website scope configuration app/code/core/Mage/Customer/Model/Session.php78-83

Authentication Logic

• login($username, $password): Authenticates against the customer model app/code/core/Mage/Customer/Model/Session.php216-227
• setCustomerAsLoggedIn($customer): Attaches the customer object to the session and triggers renewSession() to prevent session fixation app/code/core/Mage/Customer/Model/Session.php233-237
• isLoggedIn(): Checks if the customer ID is present and validated against the database app/code/core/Mage/Customer/Model/Session.php190-193

Code-to-Entity Mapping (Customer)

Sources:

• Customer Session initialization: app/code/core/Mage/Customer/Model/Session.php76-85
• Login and session renewal: app/code/core/Mage/Customer/Model/Session.php216-237
• Login status check: app/code/core/Mage/Customer/Model/Session.php190-207

Admin Sessions

Mage_Admin_Model_Session handles the administrative area.

Admin Login Process

The flow is managed by Mage_Adminhtml_IndexController:

1. Pre-login: preloginAction checks credentials and handles 2FA requirements app/code/core/Mage/Adminhtml/controllers/IndexController.php51-71 This calls Mage_Admin_Model_Session::prelogin() which triggers user authentication and flags if 2FA is needed app/code/core/Mage/Admin/Model/Session.php140-155
2. Login: Mage_Admin_Model_Session::login() authenticates the user via Mage_Admin_Model_User, calls renewSession(), and initializes the ACL app/code/core/Mage/Admin/Model/Session.php161-191
3. Startup: Users are redirected to their profile-specific startup page app/code/core/Mage/Adminhtml/controllers/IndexController.php40-41

Admin Session Security

• Indirect Logout: Admin sessions are invalidated if accessed from an unauthorized context or via an unallowed SID app/code/core/Mage/Admin/Model/Session.php107-121
• 2FA Integration: The session tracks if a 2FA verification code is required during the login sequence app/code/core/Mage/Admin/Model/Session.php140-155
• Password Changes: If a user's password is changed, the session tracks this via setUserPasswordChanged(true) app/code/core/Mage/Admin/Model/User.php159-162

Sources:

• Admin Index Controller: app/code/core/Mage/Adminhtml/controllers/IndexController.php13-100
• Admin Session Login: app/code/core/Mage/Admin/Model/Session.php161-191
• Indirect Logout Logic: app/code/core/Mage/Admin/Model/Session.php107-121
• 2FA Pre-login: app/code/core/Mage/Admin/Model/Session.php140-155

API Sessions

API sessions (Mage_Api_Model_Session) differ from web sessions as they are often stateless or managed via explicit session IDs.

• Initialization: Generates a unique session ID based on time and entropy app/code/core/Mage/Api/Model/Session.php25-30
• Authentication: Validates API keys against Mage_Api_Model_User app/code/core/Mage/Api/Model/User.php237-250
• Expiration: API sessions expire based on a specific api/config/session_timeout configuration app/code/core/Mage/Api/Model/Session.php182-189

Sources:

• API Session Start: app/code/core/Mage/Api/Model/Session.php25-30
• API User Authentication: app/code/core/Mage/Api/Model/User.php237-250
• API Session Expiration: app/code/core/Mage/Api/Model/Session.php182-189

Configuration Reference

Path	Description	Constant Reference
global/session_save	Storage type (files or redis)	XML_NODE_SESSION_SAVE
global/session_save_path	Path for file storage	XML_NODE_SESSION_SAVE_PATH
web/cookie/cookie_lifetime	Frontend session duration	XML_PATH_COOKIE_LIFETIME
admin/security/session_cookie_lifetime	Admin session duration	N/A
web/session/use_remote_addr	Validate client IP	XML_PATH_USE_REMOTE_ADDR
web/session/use_http_user_agent	Validate User Agent	XML_PATH_USE_USER_AGENT
api/config/session_timeout	API session duration	N/A

Sources:

• Mage_Core_Model_Session_Abstract configuration nodes: app/code/core/Mage/Core/Model/Session/Abstract.php43-57
• API timeout usage: app/code/core/Mage/Api/Model/Session.php188