Documentation/README.phpgacl

   1              Hints for Using phpGACL with OpenEMR
   2           by Rod Roark <rod at sunsetsystems dot com>
   3
   4 Installation Instructions
   5
   6 phpGACL access controls are embedded and installed by default in OpenEMR
   7 versions 2.9.0.3 or later.  The administration of the access controls is
   8 within OpenEMR in the admin->acl menu. The library/acl.inc file can be
   9 easily modified to turn off phpGACL or to use an external version.
  10
  11
  12 Upgrading Instructions
  13
  14 After you have upgraded to a new version of OpenEMR, you should
  15 run the acl_upgrade.php program using your web browser
  16 (e.g. http://openemr.location/acl_upgrade.php). This will ensure your
  17 phpGACL database contains all the required OpenEMR Access Control
  18 Objects.
  19
  20
  21 For Developers
  22
  23 If you add a new Access Control Object to the OpenEMR codebase, then
  24 also add it to the following three sites:
  25 1. Header notes of the library/acl.inc file
  26 2. acl_setup.php file
  27 3. acl_upgrade.php file
  28
  29
  30 Miscellaneous Information
  31 (the below information is only applicable
  32 to OpenEMR versions less than 2.9.0.3 or to users who choose to
  33 install an external version of phpGACL)
  34
  35 If you are using an OpenEMR version previous to 2.9.0.3, then phpGACL
  36 has not been automatically installed.  Setting it up takes some careful
  37 study, planning and a bit of time.  If you don't have the time then you
  38 should hire an experienced person to set things up for you.  Helpful
  39 installation and configuration instructions can be found on the wiki at the
  40 www.open-emr.org site.
  41
  42 Alternatively, it's possible to set up your own access rules without
  43 using phpGACL by customizing the code in library/acl.inc.  See that
  44 module for more information.
  45
  46 phpGACL is available from http://phpgacl.sourceforge.net/.  Read
  47 its documentation and install it according to its instructions.
  48 Helpful installation and configuration instructions can also be
  49 found on the wiki at the www.open-emr.org site.
  50
  51 The admin GUI needs to be protected, so add something like this
  52 to your Apache configuration:
  53
  54   <Directory  "/var/www/phpgacl/admin">
  55     AuthType Basic
  56     AuthName "ACL Administrators"
  57     AuthUserFile  /var/www/phpgacl/admin/.htpasswd
  58     Require valid-user
  59   </Directory>
  60
  61 And of course make an associated .htpasswd file at the corresponding
  62 location.  See "man htpasswd2" if you have Apache 2.  Yes, it's quite
  63 odd that the phpGACL GUI does not control access to itself!
  64
  65 Note that OpenEMR does not use AXOs, so ignore the AXO Group Admin
  66 tab and other references to AXOs.
  67
  68 After you have installed phpGACL and modified library/acl.inc
  69 appropriately, you should run the acl_setup.php program using your
  70 web browser (e.g. http://openemr.location/acl_setup.php).  This will
  71 create some required and sample objects in the phpGACL database for
  72 OpenEMR.
  73
  74 acl_setup.php creates required Access Control Objects (ACOs, the
  75 things to be protected), several sample Access Request Object (AROs
  76 are the users requesting access), and their corresponding sections.
  77 You may also create such objects yourself using the "ACL Admin"
  78 tab of the phpGACL GUI.
  79
  80 The Access Control Objects (ACOs) for OpenEMR have a very specific
  81 structure.  This is described in the file library/acl.inc, which
  82 you must also modify in order to enable use of phpGACL.
  83
  84 You must manually create an ARO in this "users" section for each
  85 OpenEMR user (except for the "admin" user which the setup program
  86 creates).  The Value column must be the user's OpenEMR login name,
  87 and the Name column can (should) be their full name.
  88
  89 By the way, values in the "Order" columns do not seem to be important.
  90 I just plug in "10" for everything.  Names are cosmetic but should be
  91 meaningful to you.  What really matters is the Value column.
  92
  93 Then you should define or modify groups and assign users (AROs) to
  94 them using the "ARO Group Admin" tab of the GUI.  These can be
  95 structured any way you like.  Here is one example of a group
  96 heirarchy for a clinic setting:
  97
  98   Users
  99     Accounting
 100     Administrators
 101     Assistants
 102       Front Office
 103       Lab
 104       Medical
 105     Nurses
 106     Physicians
 107
 108 To see your access rules, click the "ACL List" tab.  To make corrections
 109 click the corresponding Edit link on the right side; this will open the
 110 ACL Admin tab with the corresponding selections already made, which you
 111 can then change as desired and resubmit.  Note that the ACL List page
 112 also provides for deleting entries.
 113
 114 The ACL Admin tab is also used to assign permissions.  This is
 115 a really confusing "write only" interface, but thankfully you won't
 116 have to use it every day!  Mostly what you will do here is highlight
 117 a group from the box on the right, and also select some ACOs from the
 118 top section by highlighting them and clicking the ">>" button.
 119 Then if "write" or "wsome" or "addonly" access applies, key in that
 120 as the return value, otherwise a return value is not required.  Then
 121 click the Submit button to save that particular access rule.  Repeat
 122 until all your ACL rules are defined.