mods/wiki/plugins/auth-liveuser/README

   1 _______________________________
   2 eWiki LiveUser Auth/Perm Plugin
   3 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
   4 ! License
   5
   6 The required LiveUser library and these plugins are separately licensed under
   7 the Lesser GPL. The copyright on the plugins is held by The Burgiss Group,
   8 LLC. Bugs and change requests may be submitted to the ewiki mailing list,
   9 ewiki@freelists.com.
  10
  11 ! Authors
  12
  13 The bundled LiveUser PEAR package was developed by Markus Wolff, and
  14 associated contributors <http://pear.php.net/package/LiveUser/>. This plugin
  15 was developed at the Burgiss Group <http://burgiss.com/> by the following
  16 developers:
  17
  18         * andy fundinger <andy@burgiss.com>
  19         * alex wan <alex@burgiss.com>
  20         * jeremy mikola <jmikola@arsjerm.net>
  21
  22 __NOTE__: The permissions component of this plugin depends the following
  23 plugin (path reletive from ewiki root): plugins/lib/protmode.php
  24
  25 ! Introduction
  26
  27 The purpose of this plugin is to provide eWiki with a means of handling
  28 access permissions for all of its pages, based on users and groups.
  29 Permissions are set as a ring level (comparable to eWiki access rings) for a
  30 right and pagename combination. Rights are associated with group names,
  31 which may then contain users. For all intensive purposes, rights and groups
  32 function as a pair of one entity; the right being associated with the page
  33 permissions and the group being associated with users.
  34
  35 When a user accesses a page, his highest available ring level for the page
  36 is calculated based on all group memberships, and that level is used to
  37 denote what actions may be performed on that page. eWiki actions may be
  38 mapped to one of these base ring levels, so that page permissions may also
  39 be used to govern custom actions for other plugings (to a degree). The
  40 available base levels are as follows:
  41
  42         * view
  43         * forum (write page comments)
  44         * edit (edit a page)
  45         * manage (advanced editing, such as modifying a page's permissions)
  46         * admin
  47
  48 There are several rights/groups constructed by the plugin by default, which
  49 have reserved used. These are listed below:
  50
  51         * NotLoggedIn
  52         * LoggedIn
  53         * LW_Publisher
  54         * LW_Admin
  55
  56 The NotLoggedIn and LoggedIn groups are used to signify the generic class of
  57 unauthenticated and logged-in users, respectively. The group of NotLoggedIn
  58 is also a superset of the group of LoggedIn users, so that permissions
  59 satisfied by unauthenticated users will also be satisfied by logged-in
  60 users; however, the opposite does not hold. Members of the LW_Publisher that
  61 already have the rights to edit an eWiki page will also be able to make that
  62 page publicly viewable by members of the NotLoggedIn group. Note that a
  63 member of the LW_Publisher group still requires the fundemental edit rights
  64 on a pagename first. Lastly, the LW_Admin group is given access to the
  65 plugin's administration pages by default, allowing a member of this group to
  66 modify page permissions, user accounts, and rights/groups.
  67
  68 This plugin uses several eWiki plugin hooks. The following eWiki plugin
  69 pagenames are reserved:
  70
  71         * LogIn
  72         * LogOut
  73         * ChangePassword
  74         * ChangePrefs
  75         * AdminAddUsers (administration interfaces)
  76         * AdminPerms
  77         * AdminPermsReport
  78         * AdminPrefs
  79         * AdminRights
  80         * AdminUsers
  81
  82 The following authentication hooks are made:
  83
  84         * $ewiki_plugins['auth_query'][0] for querying logged-in user status
  85         * $ewiki_plugins['auth_perm'][0] for querying a page permission
  86
  87 In order the handle page permissions, the eWiki edit-page form is appended
  88 with form components to manage the page permissions and toggle the
  89 'published' status of a page, which allows it to be viewed by users that are
  90 not logged in. Two plugin callbacks are added to each of the following
  91 hooks:
  92
  93         * $ewiki_plugins['edit_form_append'][]
  94         * $ewiki_plugins['edit_save'][]
  95
  96 The plugin also adds a manage action hook to the array of available page
  97 actions. The action (for text, plugin, and binary pages) hooks are as follows:
  98
  99         * $ewiki_plugins['action_always']['manage']
 100         * $ewiki_plugins['action_binary']['manage']
 101
 102 ! Installation
 103
 104 The included files (excluding the LiveUser package), should be extracted and
 105 moved to the eWiki plugins directory, or some other directory where eWiki
 106 will include files from. The LiveUser package should then be extracted to the
 107 PEAR directory, or some other path within PHP's include-path list.
 108
 109 __NOTE__: The above installation instructions for the LiveUser package do not
 110 import LiveUser into PEAR's package list. At the present time, this plugin can
 111 not be guarenteed to work with all versions of LiveUser; therefore, a tested
 112 LiveUser release will be made available for use with this plugin.
 113
 114 From the directory where the plugin files were extracted, open
 115 liveuser_conf.php and configure the following:
 116
 117         * prefix for internal table names
 118         * mappings of eWiki actions to perm rings
 119         * public and default perm filters
 120         * log file for deleted users
 121         * LiveUser database connection
 122
 123 The LiveUser configuration may optionally be edited (documentation may be
 124 found in the LiveUser package), however no changes should be necessary.
 125 Following liveuser_conf.php, open liveuser_setup.php and configure the
 126 following:
 127
 128         * eWiki database connection
 129         * LiveUser database connection (if needed)
 130         * LiveUser properties, rights, groups, and default page rights and users
 131
 132 It is not necessary to declare all rights, groups, and users in the setup
 133 file, as the included admin pages may be used to do so after installation;
 134 however, you should ensure that at least one user is added to the admin
 135 group, as shown by example in the setup file.
 136
 137 Following the configuration of liveuser_conf.php and liveuser_setup.php, the
 138 LiveUser database tables must be created. Within the extracted LiveUser/
 139 directory, an sql/ directory will contain necessary scripts to build the
 140 LiveUser database. The following files should be executed for this purpose:
 141
 142         * Auth_DB.sql
 143         * Perm_DB_Complex.sql
 144
 145 The LiveUser tables should now be properly configured, and now
 146 liveuser_setup.php must be executed to build the remaining database tables
 147 for the plugin. It is suggested that this file be executed from a console
 148 prompt (`php liveuser_setup.php`). It will generate output as it constructs
 149 the database and necessary entities, some of which will be PHP code to be
 150 inserted into liveuser_conf.php, which will define constants of some created
 151 entities. This script is able to be executed safely multiple times if the
 152 generated PHP code is needed again for some reason; however, it will not
 153 generate output about entity creation if those entities already exist.
 154
 155 For user preferences support, the file liveuser_setup_prefs.php may be
 156 edited and executed (much like liveuser_setup.php).to build user preference
 157 fields and make them available by default. Althougth the functions in
 158 pref_liveuser.php are usable on their own, basic interfaces are available
 159 through the following page names:
 160
 161         * ChangePrefs
 162         * AdminPrefs
 163
 164 ChangePrefs, along the lines of ChangePassword, is intended to be used by the
 165 user himself to modify his account. It will allow the user to edit the values
 166 for any preferences that have been toggled 'public', that is, allowed to be
 167 modified by users. The AdminPrefs page will allow an administrator to modify
 168 available fields, along with their default values and public mode. At this time,
 169 there is no interface for the administrator to edit the preferences of users;
 170 therefore, non-public fields are inaccessible through these interfaces, and can
 171 only be employed through the function API. This will be changed in a future release.
 172
 173 With liveuser_setup.php executed, and its output successfully inserted into
 174 liveuser_conf.php, the only remaining step is to include the plugin from
 175 eWiki's config.php file. One of the following files may be included,
 176 depending on whether simple authentication (login only) or more advanced
 177 permissions (login and rights) are required:
 178
 179         * auth_liveuser.php OR
 180         * perm_liveuser.php
 181
 182 If auth_liveuser.php is initially selected and it becomes necessary to
 183 switch to perm_liveuser.php at a later time, it may also be necessary to run
 184 liveuser_setup.php again in order to apply default permissions to all
 185 current pages in the eWiki database, otherwise some pages would have no
 186 permissions assigned and thus be inaccessible.
 187
 188 __IMPORTANT__: If only auth_liveuser.php is chosen, judgement should be exercised
 189 in properly protecting the liveuser_*_gui.php files, which contain the
 190 admin scripts, from all logged-in users. Without perm_liveuser.php active,
 191 these files cannot be protected by the plugin's permissions system. A
 192 possible solution would be to abort those pages if the handle of the
 193 current user does not match a reserved name. The following pagenames will
 194 be added to the list of eWiki plugin pages for the purpose of administration:
 195
 196         * AdminAddUsers
 197         * AdminPerms
 198         * AdminPermsReports
 199         * AdminPrefs
 200         * AdminRights
 201         * AdminUsers
 202
 203 It should be noted that whenever a new right (permission) is created, a
 204 corresponding group should also be created (the option exists) so that they
 205 may be linked together and users may then later be added to that group in
 206 order to inherit the right.