Revision as of 16:56, 23 May 2019

Overview

Sessions are a way to preserve data across subsequent page loads and is a fundamental element in a web application design. Sessions are a building block for functionality such as logins and shopping carts.

Sessions must have dedicated storage location and be available to the web application. WHMCS supports session storage for either file-backed and database-backed sessions. The most common choice is file sessions, but database sessions can be advantageous for some environments.

File Sessions

File sessions are the most common choice since it is the default for PHP environments. Little to no configuration is required, either by a system administrator or a web application, in order for session utility to function immediately. File-backed sessions has historically been the first and best choice for single-instance web applications.

When file-backed sessions are used, web applications write a file to a configured directory for each unique visitor. If the server that hosts your WHMCS is shared with other applications or individuals, it is possible that those applications or individuals can read and write to that directory as well. Sharing this directory introduces a security risk since sessions may contain sensitive information. As well, it is very common for applications to implicitly trust the information within these files as if only it would have access to them. Please consult with your system administrator, web server documentation, or server's control panel documentation for more guidance related to the evaluation and mitigation of any risks for your environment.

Configuration

No configuration is required for WHMCS to utilize the default PHP file session storage.

Database Sessions

Database sessions are also a common choice for PHP environments. A web application must provide integration code in order to store session data in a database.

Utilizing a system service, such as a database server, has the benefit of supporting multiple application instances, which may be an important part of a high-availability/scalable infrastructure design. When using database stored sessions, the inherent risks associated with file-backed session permissions (as mentioned above) are mitigated. Some web applications allow the configuration of a dedicated database just for session data. This may help reduce the impact in the event of a SQL injection attack.

Configuration

To utilize database session storage a simple configuration value must be placed with configuration.php.

$session_handling = 'database';

Session data will be stored in the same database itemized by other configuration values.

Advanced Configuration

If you need, advanced configuration options are possible by specifying a more elaborate value for $session_handling.

Below is an example of the structure and key/value pairs required for advanced configuration:

$session_handling = [
  'serviceProvider' => '\\WHMCS\\Session\\Database\\ServiceProvider',  //do not alter this line
  'database' => [
    'lifetime' => 24 * 60, //provide a session lifetime in minutes, default is 1440 (1 day)
    'connectionAlias' => 'sessionsDbConnection',  //provide internal handler name other than "default"
    'config' => [
      'host' => 'my.host.local',   //provide hostname or IP of database server
      'database' => 'db_name',     //provide name of database to use
      'username' => 'db_user',     //provide username for authenticate at server
      'password' => 'db_password', //provide password for authentication at server
    ],
    'table' => 'user_sessions', //provide name of table; see tblsessions in WHMCS for schema
    'logErrors' => false, //whether session SQL errors should be recorded to activity log when possible
  ],
];

WHMCS does not manage tables or schema outside the core database. If you provide an advanced configuration you will need to ensure the named database has the appropriate target table and schema. A copy of the appropriate table schema is distributed with WHMCS and located at resources/sql/install/tblsessions.schema.sql