doc/access_levels.txt

   1                         FrontAccounting access control system
   2                         =====================================
   3
   4 Since version 2.2 FrontAccounting has new, flexible access level control system.
   5 In contrast to previous system based on arrays stored in global config.php file,
   6 the new system uses per company security_roles tables. This approach makes
   7 FrontAccounting finally suitable for multicompany installation involving
   8 various types of companies.
   9
  10 1. Security schema
  11 ------------------
  12
  13 New access control system uses following concepts:
  14
  15 . Security area - elementary fragment of application functionality which
  16         is placed under control of access system;
  17
  18 . Security role - set of security areas which is accessable for user with
  19         some role in company;
  20
  21 . Security section - a couple of security areas of similar application grouped
  22         together to make roles defining easier.
  23
  24 Security areas stored in global $security_areas array have two properties:
  25 identifier (in numeric and string form) and description. Description is used
  26 only to identify area in security roles editor, while string identifiers are
  27 used in various places of source code to be checked against current user
  28 permissions.
  29
  30 Every security area belongs to one security section, which can be considered
  31 as upper level of access control. All defined security sections are stored
  32 in global $security_sections array together with descriptions used in roles
  33 editor.
  34
  35 2. Access Setup
  36 ---------------
  37
  38 FrontAccounting since version 2.2 has role based access system. It means that
  39 every user defined in a system has assigned role related to his position in
  40 company. For any user only security areas which belong to user's role are
  41 accesible.
  42
  43 To grant access to any security area for any role administrator first have to
  44 make accessible also related area's security section. Switching security section
  45 off disables access to all related security areas.
  46
  47 Security roles predefined in FrontAccounting initial database can be customized
  48 or completely rewritten by administrator according to company internal security
  49 policy.
  50
  51 Some security areas crucial for overall site security are accesible only for
  52 administrators of the first installed company, who can be considered as
  53 superadmins. All those important areas are grouped in section 0
  54 (System administration), and as of FA 2.2 involve:
  55         . Installing/update of companies
  56         . Installing/update language message files
  57         . Installing/activation system extensions
  58         . System upgrades
  59
  60 3. How all it works
  61 -------------------
  62
  63 Every user defined in a system has one security role assigned. List of
  64 all accesible security areas/sections codes is retrieved from security_roles
  65 table on user login, and cached in user session variable for fast checking.
  66 Every page in a system has at least one related security area, which is
  67 assigned to $page_security global variable at the beginning of the page script.
  68
  69 Page access control is performed by check_page_security() call in
  70 page() function (used for every displayed page) or by can_access_page()
  71 call in FrontReport constructor for all reports. When user has granted access
  72 rights to checked security area, selected page is displayed or report generated.
  73 Otherwise information message is displayed and page/report generation is aborted.
  74
  75 4. Security extensions
  76 ----------------------
  77
  78 FrontAccounting application accepts two forms of functionality additions:
  79 extension modules and extension plugins. Both types of extensions can use
  80 standard security areas/sections to control access to introduced functionality,
  81 or define its own security areas and/or sections.
  82
  83 To extend access control system with additional sections/areas, extension
  84 need to contain a file were all new extensions are defined. The access control
  85 file relative path should be entered during extension install process on
  86 Install/Activate Extensions page, or as 'access' property during direct entry
  87 in installed_extensions.php file.
  88
  89 Every php script using security extensions have to call function
  90 add_security_extensions() to make defined extensions active. The call should
  91 be placed between session.inc inclusion and page() or FrontReport() call.
  92
  93 5. Example access control configuration file
  94 --------------------------------------------
  95
  96 This is content of sample access control file for CRM extension module:
  97
  98 <?php
  99 /*
 100         Define security section codes
 101 */
 102 define('SS_CRM_C',      101<<8);
 103 define('SS_CRM',        102<<8);
 104 define('SS_CRM_A',      103<<8);
 105
 106 /*
 107         Additional security sections for CRM module
 108 */
 109 $security_sections[SS_CRM_C] = _("CRM configuration");
 110 $security_sections[SS_CRM] = _("CRM transactions");
 111 $security_sections[SS_CRM_A] = _("CRM analytics");
 112 /*
 113         Additional security areas for CRM module
 114 */
 115 $security_areas['SA_CRMSETUP'] = array(SS_CRM_C|1, _("CRM module setup"));
 116 $security_areas['SA_CRMCONTACTENTRY'] = array(SS_CRM|1, _("Customer contact entry"));
 117 $security_areas['SA_CRMANALYITCS'] = array(SS_CRM|1, _("Pre-sale contact analytics"));
 118
 119 ?>
 120
 121 The exact values used for security section codes are not very important,
 122 as they are rewritten by access control system during integration of
 123 access extensions. Therefore numeric values of security sections/areas should
 124 never be used directly in the extensions source. Use string representations
 125 instead when needed, or values retrieved from $security_areas array.
 126