_______________________________
eWiki LiveUser Auth/Perm Plugin

! License 

The required LiveUser library and these plugins are separately licensed under
the Lesser GPL. The copyright on the plugins is held by The Burgiss Group,
LLC. Bugs and change requests may be submitted to the ewiki mailing list,
ewiki@freelists.com.

! Authors

The bundled LiveUser PEAR package was developed by Markus Wolff, and
associated contributors <http://pear.php.net/package/LiveUser/>. This plugin
was developed at the Burgiss Group <http://burgiss.com/> by the following
developers:

	* andy fundinger <andy@burgiss.com>
	* alex wan <alex@burgiss.com>
	* jeremy mikola <jmikola@arsjerm.net>

__NOTE__: The permissions component of this plugin depends the following
plugin (path reletive from ewiki root): plugins/lib/protmode.php

! Introduction

The purpose of this plugin is to provide eWiki with a means of handling
access permissions for all of its pages, based on users and groups.
Permissions are set as a ring level (comparable to eWiki access rings) for a
right and pagename combination. Rights are associated with group names,
which may then contain users. For all intensive purposes, rights and groups
function as a pair of one entity; the right being associated with the page
permissions and the group being associated with users.

When a user accesses a page, his highest available ring level for the page
is calculated based on all group memberships, and that level is used to
denote what actions may be performed on that page. eWiki actions may be
mapped to one of these base ring levels, so that page permissions may also
be used to govern custom actions for other plugings (to a degree). The
available base levels are as follows:

	* view
	* forum (write page comments)
	* edit (edit a page)
	* manage (advanced editing, such as modifying a page's permissions)
	* admin
	
There are several rights/groups constructed by the plugin by default, which
have reserved used. These are listed below:

	* NotLoggedIn
	* LoggedIn
	* LW_Publisher
	* LW_Admin
	
The NotLoggedIn and LoggedIn groups are used to signify the generic class of
unauthenticated and logged-in users, respectively. The group of NotLoggedIn
is also a superset of the group of LoggedIn users, so that permissions
satisfied by unauthenticated users will also be satisfied by logged-in
users; however, the opposite does not hold. Members of the LW_Publisher that
already have the rights to edit an eWiki page will also be able to make that
page publicly viewable by members of the NotLoggedIn group. Note that a
member of the LW_Publisher group still requires the fundemental edit rights
on a pagename first. Lastly, the LW_Admin group is given access to the
plugin's administration pages by default, allowing a member of this group to
modify page permissions, user accounts, and rights/groups.
	
This plugin uses several eWiki plugin hooks. The following eWiki plugin
pagenames are reserved:

	* LogIn
	* LogOut
	* ChangePassword
	* ChangePrefs
	* AdminAddUsers (administration interfaces)
	* AdminPerms
	* AdminPermsReport
	* AdminPrefs
	* AdminRights
	* AdminUsers

The following authentication hooks are made:

	* $ewiki_plugins['auth_query'][0] for querying logged-in user status
	* $ewiki_plugins['auth_perm'][0] for querying a page permission
	
In order the handle page permissions, the eWiki edit-page form is appended
with form components to manage the page permissions and toggle the
'published' status of a page, which allows it to be viewed by users that are
not logged in. Two plugin callbacks are added to each of the following
hooks:

	* $ewiki_plugins['edit_form_append'][]
	* $ewiki_plugins['edit_save'][]
	
The plugin also adds a manage action hook to the array of available page
actions. The action (for text, plugin, and binary pages) hooks are as follows:

	* $ewiki_plugins['action_always']['manage']
	* $ewiki_plugins['action_binary']['manage']

! Installation

The included files (excluding the LiveUser package), should be extracted and
moved to the eWiki plugins directory, or some other directory where eWiki
will include files from. The LiveUser package should then be extracted to the
PEAR directory, or some other path within PHP's include-path list.

__NOTE__: The above installation instructions for the LiveUser package do not
import LiveUser into PEAR's package list. At the present time, this plugin can
not be guarenteed to work with all versions of LiveUser; therefore, a tested
LiveUser release will be made available for use with this plugin.

From the directory where the plugin files were extracted, open
liveuser_conf.php and configure the following:

	* prefix for internal table names
	* mappings of eWiki actions to perm rings
	* public and default perm filters
	* log file for deleted users
	* LiveUser database connection
	
The LiveUser configuration may optionally be edited (documentation may be
found in the LiveUser package), however no changes should be necessary.
Following liveuser_conf.php, open liveuser_setup.php and configure the
following:

	* eWiki database connection
	* LiveUser database connection (if needed)
	* LiveUser properties, rights, groups, and default page rights and users
	
It is not necessary to declare all rights, groups, and users in the setup
file, as the included admin pages may be used to do so after installation;
however, you should ensure that at least one user is added to the admin
group, as shown by example in the setup file.

Following the configuration of liveuser_conf.php and liveuser_setup.php, the
LiveUser database tables must be created. Within the extracted LiveUser/
directory, an sql/ directory will contain necessary scripts to build the
LiveUser database. The following files should be executed for this purpose:
	
	* Auth_DB.sql
	* Perm_DB_Complex.sql
	
The LiveUser tables should now be properly configured, and now
liveuser_setup.php must be executed to build the remaining database tables
for the plugin. It is suggested that this file be executed from a console
prompt (`php liveuser_setup.php`). It will generate output as it constructs
the database and necessary entities, some of which will be PHP code to be
inserted into liveuser_conf.php, which will define constants of some created
entities. This script is able to be executed safely multiple times if the
generated PHP code is needed again for some reason; however, it will not
generate output about entity creation if those entities already exist.

For user preferences support, the file liveuser_setup_prefs.php may be
edited and executed (much like liveuser_setup.php).to build user preference
fields and make them available by default. Althougth the functions in
pref_liveuser.php are usable on their own, basic interfaces are available
through the following page names:

	* ChangePrefs
	* AdminPrefs
	
ChangePrefs, along the lines of ChangePassword, is intended to be used by the
user himself to modify his account. It will allow the user to edit the values
for any preferences that have been toggled 'public', that is, allowed to be
modified by users. The AdminPrefs page will allow an administrator to modify
available fields, along with their default values and public mode. At this time,
there is no interface for the administrator to edit the preferences of users;
therefore, non-public fields are inaccessible through these interfaces, and can
only be employed through the function API. This will be changed in a future release.

With liveuser_setup.php executed, and its output successfully inserted into
liveuser_conf.php, the only remaining step is to include the plugin from
eWiki's config.php file. One of the following files may be included,
depending on whether simple authentication (login only) or more advanced
permissions (login and rights) are required:

	* auth_liveuser.php OR
	* perm_liveuser.php

If auth_liveuser.php is initially selected and it becomes necessary to
switch to perm_liveuser.php at a later time, it may also be necessary to run
liveuser_setup.php again in order to apply default permissions to all
current pages in the eWiki database, otherwise some pages would have no
permissions assigned and thus be inaccessible.

__IMPORTANT__: If only auth_liveuser.php is chosen, judgement should be exercised
in properly protecting the liveuser_*_gui.php files, which contain the
admin scripts, from all logged-in users. Without perm_liveuser.php active,
these files cannot be protected by the plugin's permissions system. A
possible solution would be to abort those pages if the handle of the
current user does not match a reserved name. The following pagenames will
be added to the list of eWiki plugin pages for the purpose of administration:

	* AdminAddUsers
	* AdminPerms
	* AdminPermsReports
	* AdminPrefs
	* AdminRights
	* AdminUsers

It should be noted that whenever a new right (permission) is created, a
corresponding group should also be created (the option exists) so that they
may be linked together and users may then later be added to that group in
order to inherit the right.
