Authentication & Sessions

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/api.php
• README.md
• scripts/AGENT_NOTES.md
• AGENT_NOTES.md
• config/AGENT_NOTES.md
• wiki/Security.md
• api-examples/AGENT_NOTES.md

Introduction

The IT Management System utilizes a session-based authentication model coupled with Cross-Site Request Forgery (CSRF) protection to secure its multi-tenant environment. Unlike modern stateless architectures, this project relies on native PHP sessions and persistent cookies to maintain user state and enforce data isolation across different companies.

The authentication system is designed to provide a secure entry point via a dedicated login page while ensuring that all subsequent data interactions are strictly scoped by the user's active session and company context. This mechanism is critical for the project's multi-tenant architecture, where data isolation is a primary requirement.
Sources: scripts/api.php:159-165, AGENT_NOTES.md:12-14, README.md:14-16

Authentication Architecture

The system employs a centralized authentication flow that requires a valid username (email) and password. Once authenticated, the server establishes a session and assigns a company_id to the session context, which is then used to filter all database queries.

Key Security Components

• Session Management: Uses standard PHPSESSID cookies to track authenticated users.
• CSRF Protection: Mandatory csrf_token in POST request bodies or X-CSRF-Token headers for all data-mutating operations.
• Tenant Isolation: The company_id is resolved server-side from the session, preventing clients from accessing data belonging to other tenants by simply changing a payload field.
• Vault Security: For specific modules like Passwords, an additional vault_key is established in the session to unlock encrypted data.

Sources: scripts/api.php:177-184, scripts/AGENT_NOTES.md:46-52, wiki/Security.md:54-58

Authentication Flow Diagram

The following sequence diagram illustrates the process of establishing an authenticated session and subsequent protected API calls.

Session and Multi-Tenancy

Multi-tenancy is enforced through the session's company_id. Developers are explicitly instructed not to include company_id in API payloads, as the system resolves this context server-side.

Session Variable	Description
user_id	Unique identifier of the currently logged-in user.
company_id	Current tenant context used for SQL filtering.
csrf_token	Token used to validate POST requests.
vault_key	Key required to access the encrypted Passwords module.

Sources: scripts/api.php:163-165, scripts/AGENT_NOTES.md:49-52, config/AGENT_NOTES.md:9-12

CLI Session Bypass

For development, testing, and automated tasks (like screenshot capture), the system provides a bypass_login.php utility. This script allows establishing a valid session without manual UI interaction by:

1. Manually creating a session file in the server's session directory.
2. Adjusting permissions so the web server can read the CLI-created session.
3. Automatically setting the vault_key and default company_id.

Sources: scripts/AGENT_NOTES.md:46-55

Security Auditing and Maintenance

The project includes several tools to audit the implementation of authentication and session security:

• CSRF Coverage Audit: php scripts/check_csrf_coverage.php identifies POST handlers missing validation.
• SQL Injection Audit: php scripts/check_sql_injection_coverage.php ensures prepared statements are used alongside session-based filters.
• Multi-Tenant Leak Scan: php scripts/check_multi_tenant_leaks.php scans for queries missing the company_id filter.

Sources: wiki/Security.md:7-12, scripts/scripts.php:337-342, scripts/scripts.php:358-362

API Authentication Example

Interacting with the system's internal APIs requires capturing the session cookie and extracting the CSRF token from the page content.

# Example: Authenticating and calling a protected endpoint via cURL
# 1. Login and store session cookies
curl -c cookies.txt -X POST "http://localhost/it-management/login.php" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data "email=Admin&password=Admin&csrf_token=XYZ"

# 2. Call a protected JSON endpoint
curl -b cookies.txt -X POST "http://localhost/it-management/includes/get_ports.php" \
     -H "Content-Type: application/json" \
     -d '{"switch_id": 1, "csrf_token": "XYZ"}'

Sources: scripts/api.php:186-194, api-examples/AGENT_NOTES.md:10-12

Conclusion

Authentication and Session management in this system serve as the foundational layer for both security and multi-tenancy. By binding every request to a server-side session context and enforcing strict CSRF validation, the architecture prevents unauthorized data access and cross-tenant leakage. Developers must ensure that all new modules strictly adhere to these session-scoped data access patterns.
Sources: AGENT_NOTES.md:9-14, config/AGENT_NOTES.md:6-14