Documentation/README.phpgacl

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