[Top]

User session management [PHP]

Framework for User session management
The framework consists on a set of PHP pages allowing to manage users and roles, logon as a User or a Guest and access allowed use cases.
The user repository is persisted in a MySQL database.
The intention is to provide a framework, ie a toolkit on top of which it is very simple to verify the authentication and the privileges of the logged user.
Basically the framework may serve to authenticate users at site level; however the access of a specific user to a specific page is also managed.
Both form-based login and HTTP-based login (with a browser popup) are possible.
Entity model
The entities representing an authentication problem are: the user, the Role and the notion that a User has a specific role.
Finally a Role is associated with a Use Case and the framework determines if a user has access to a Use case.
The entites are:
  • the User represents the individual accessing the system - its attributes are (Name, Common Name, Password, EMail, IsEnabled) and it is persisted in the database,
  • the Role represents a user profile (or an Actor in UML) - its attributes are (ID, Name, IsEnabled) and it is persisted in the database,
  • the Role of the User represents the predicate 'the User may play the Role' - its attribute is (IsEnabled) and it is persisted in the database,
  • the Use Case represents a specific interaction between the user and the system - the Use Cases are not persisted but are associated with Roles in the configuration file sitesettings.inc.
Structure of a page
The generated pages have a simple layout but all HTML elements have a class or an id so it is possible to decorate any element by using CSS .
These pages are free of TABLE elements used for formatting only.
Two CSS files are foreseen in the package: this yellow layout and a more colored one.
A HTML page contains 5 parts:
  • the HEAD , included from the file header.inc ,
  • the title of the application, included from the file headerapplication.inc ,
  • the actual content of the page,
  • a contextual footer,
  • the menu of the application, included from the file menu.inc .
Apache configuration
File extensions are .php , .inc and .htm .
As the .htm or .inc files may contain PHP scripts, the following Apache directive should be used (usually in a file named .htaccess ) :
AddType application/x-httpd-php .htm
AddType application/x-httpd-php .inc
Configuration
Additional parameter files are provided and are useful to configure the database, the language and other visible labels.
The configuration is done by defining constants with DECLARE directives, ie
DECLARE(CONSTANT, 'value');
Parameters about the site are stored in the file sitesettings.inc:
  • HOME_PAGE : the page to display when the User is not authenticated,
  • LOGGED_IN_PAGE : the page to isplay when the User is just authenticated (or the main Use Case),
  • HREF_CSS : the path of the CSS for the site,
  • LBL_SITE_KEYWORDS : the keywords used in the HTML head, ie the content in
    <META HTTP-EQUIV="KEYWORDS" CONTENT="...">
  • this file also contains constants for Use Cases and Roles together with a map of accessible Use Cases by Roles:
    define (ROLE_ADMINISTRATOR, 2);
    define (ROLE_USER, 1);
    	
    define (USE_CASE_PANEL, 0);
    define (USE_CASE_MANAGE_USER, 1);
    define (USE_CASE_CHANGE_PWD, 2);
    	
    $USE_CASE_ROLES = array(
      USE_CASE_PANEL =>
        array(ROLE_USER, ROLE_ADMINISTRATOR),
      USE_CASE_MANAGE_USER =>
        array(ROLE_ADMINISTRATOR),
      USE_CASE_CHANGE_PWD =>
        array(ROLE_USER));
Parameters about the database and site fine tuning are stored in the file db_parameter.inc:
  • SERVER_HOST, DATABASE, DATABASE_USER and DATABASE_PWD are usual settings for connecting to a MySQL database,
  • LANGUAGE : the language of the site, for now only FR and EN are included.
Localized messages and labels are stored in the files label_*.inc, where * is the language of the site.
Some labels are used in any page:
  • LBL_SITE_TITLE : the title of the application,
  • LBL_SITE_SUBTITLE : the subtitle of the application,
  • LBL_EXIT : the action to leave the application (or logoff).
How to add a Use Case
The usage of the framework consists on adding new pages following the above template, and referred from the menu of the application.
The following steps describe the addition of a new use case:
  • define a new identifier ' n' for the Use Case in the file sitesettings.inc :
    define (USE_CASE_NEW, n);
  • in the same file, associate this Use Case with the dedicated roles (eg ROLE_X and ROLE_Y) in the array $USE_CASE_ROLES :
    $USE_CASE_ROLES = array(
      ...,
      USE_CASE_NEW =>
        array(ROLE_X, ROLE_Y));
  • write the pages for the Use Case (only the content and footer are specific) from the template of the file page2.htm, the minimal Use Case example,
  • protect these pages against direct access with the PHP instruction:
    verify_user_roles(USE_CASE_NEW, LOGGED_IN_PAGE);
    meaning that if the user does not have the appropriate Roles, it will be redirected to the page LOGGED_IN_PAGE,
  • add any useful constant for labels in the file labelusecases_*.inc,
  • add a menu entry for the Use Case in the file menuusecases.inc:
    if (is_use_case_allowed(USE_CASE_NEW)) {
       	echo("<li CLASS='menuitem'>");
    	echo("<a href='".PAGE_USE_CASE_NEW."'>".
    	  LBL_USE_CASE_NEW."</a>");
       	echo("</li>");
    }
    In this example, the menu item is displayed only if the user is allowed to execute the Use Case by testing the function is_use_case_allowed(USE_CASE_ID).
Logging
User actions may be stored in a log file.
By default the logging is disabled as it requires the log level and log file location settings to be set properly:
define (APP_LOG_LEVEL, APP_LOG_INFO);
define(APP_LOG_FILE, '/home/user/org.phpnet.protected/app-log.txt');
It also requires that the folder containing the log file is writable for the Apache process.
Log levels are:
  • APP_LOG_NONE: nothing is logged,
  • APP_LOG_ERROR: only errors are logged,
  • APP_LOG_WARN: warnings (eg invalid logon attempt) are logged,
  • APP_LOG_INFO: normal actions are logged,
  • APP_LOG_DEBUG: debug information is logged,
Authentication
When the following constant is set to 0:
define (AUTH_HTTP_METHOD, 0);
form-based authentication is provided by the page index.htm :
[Form-based authentication]

By setting the value of these constants:
define (AUTH_HTTP_METHOD, 1);
define (AUTH_HTTP_REALM, 'The Application');
the authentication is based on the basic HTTP authentication managed by the browser:
[HTTP authentication]
Security
After a number of invalid logon attempts (given by MAX_LOGIN_ATTEMPT), the user is disabled. The involved user and the users having the role of Administrator will receive an email.
The user and password values are parsed to avoid SQL hacks.
The pages are protected against direct access and bypassing of the logon with the PHP instruction:
verify_fingerprint(HOME_PAGE);
meaning that if the user is not authenticated, it will be redirected to the welcome page HOME_PAGE.
Download
The current version is 0.2.
The ZIP file contains the package: PHPSession.zip .
Changes since version 0.1:
  • bug fixing and improvements,
  • logging capabilities,
  • when an account is locked, the user and the Administrators are advised by mail,
  • the tables in the database have a prefix in order to store several realms in the same database,
After installation and execution of the SQL script, the user 'administrator' with password 'admin' will make the demo.
Future extensions
Some additional capabilities are planned:
  • a new user may have to change its password at first logon,
  • entities like user, role may be implemented as PHP classes,
  • the possibility to store framework and use cases files in different folders.
[Top]