**********************************************************

    authentication.txt
    
    $Id$
    
    @author gERD Schaufelberger <gerd@exit0.net>
    @copyright 2004/2005 Wombat Web Bench
    @link http://wombat.exit0.net
    @package wombat
    @subpackage manual

**********************************************************

Using Users 
===========
The Wombat Framework comes with build-in user managerment and authentication/
authorization modules/handler. Even if they are part of the base system, there
are versatile options for customization. Also authentication handlers are
desinged as adapters, it may be very easy to write another handler, that
connects Wombat to any (?) existing user-system.

Of course, the framework also runs fine without any authentication. Without 
using the authentication modules you don't have to set up any tables in the 
database etc.

Currently, Wombat comes with two authentication handler. Those are "Wombat" and
"Null". While "Wombat" links wbSite to wbUser (an user-handling class developed
for the wombat framework) the "Null" handler is just empty.

Therefore with wbAuth_Wombat you can actually login into and logout from the
current site, wbAuth_Null always results in an anonymous visitor. If you don't
need user logins etc, "Null" is the hanlder of your choice. 

The other handler "wbAuth_Wombat" uses wbUser as backend. wbUser is fully
supported by the Wombat framework and provides you with a nice adminstration
interface as well as password-renew modules etc. Also there are various
permission checking modules that work hand in hand with wbUser. This is the
bright side. 

On the dark side, wbUser may not be compatible with your custom application that
you want to run within the framework. In this case you may want to write your
own authentication handler. Even if this is not tested, it should work by
putting your adapter in next to wbAuth_Wombat-class (include/wbAuth/Wombat.php). 

Let's go back to the bright side and assume, wbUser is already set up and you
use the authentication handler "Wombat".

Basic Authentication features
=============================
The login handler is controlled by the configuration section: auth in the main
configuration. For a basic setup you just have to adjust the parameter:
<auth:flags>. A valid auth-section may look like this:

-----------------8<-----------------8<-----------------8<-----------------
<!-- 
 more configuration parameter
-->
	<auth>
        <auth:handler>Wombat</auth:handler>
		<auth:flags>enabled,approved,!new</auth:flags>
		
		<!-- null - switch of authentication plugin -->
		<auth:module>Null</auth:module>
		<auth:param />
		<auth:denied>
			<part name="title">
				<page:action>staticString</page:action>
				<page:href>Permission denied</page:href>
			</part>
			<part name="maincontent">
				<page:action>staticString</page:action>
				<page:href>Permission denied</page:href>
			</part>
		</auth:denied>
	</auth>

<!-- 
 more configuration parameter
-->
-----------------8<-----------------8<-----------------8<-----------------

Authenication handler
---------------------
Specifying the authentication handler allows to switch of the authentication 
and authorization processes. As mentioned above, you may choose between "Null"
and "Wombat" (ir implement your own handler). Also mentioned, "Null" is like if
there were no login - all users are treated as anonymous visitors. 

In order to make something happen, "Wombat" it the handler of our choice. 

Authentication flags
--------------------
The configuration value of <auth:flags> may or may not contain something, or
something else. What it means is, that it depends on the authentication handler
what can be used here. Basically, it is some kind of parameter, that can be
passed to the authentication handler during instanciation. 

The idea behind is, to add some additional parameter that must be checked to
grant a user to login. Of course, the user name and password must match, but
you may also want to validate, that the user is over 18 years old, for example. 

In other words, <auth:flags> may contain whatever the used authentication
handler understand. 

The authentication handler "Wombat" understands a comma separated list of user
flags. It also understand a prefix "!" - this is to negate a flag. What the
authentication handler "Wombat" (or better wbUser) does, is to check whether the
user's data satisfy those flags. 

For this example, if a user attempts to login with his username and password,
both, the username, password AND the listed flags will be required. In this
case, the flags "enabled" and "approved" must and the flag "new" must not be
set. With wbUser, those flags are represented as a "set" field in the
user-table.

If any of those checks fail, the user is not allowed to log in. As you may
imagine, this makes it very easy to enable or disable accounts without removing
them. 


Setup wbUser
============
As described above, the authentication handler uses wbUser as backend. Actually
wbUser implents all the features. Hence wbUser must be setup properly. 

Requirements
------------
All user data, like login-names, password and group-information will be stored
in a database. Even if the base system uses PEAR::DB (which supports various
databsase) using MySQL is recommended.

All user relevant data will be stored in three tables in the database: 
- user
- group
- usergroup

All of those tables will be defined in the global configuration - usually in 
tables.xml (see configuration value: <dstables>), e.g.:
-----------------8<-----------------8<-----------------8<-----------------
<configuration>
	<xinc href="/defines.xml" once="yes" />

	<tables>
 		<!-- authentication tables -->
		<table name="user" table="gsuser" primary="uid">
			<avoiddublicate>user</avoiddublicate>
			<delete>flags=deleted</delete>
		</table>
		
		<table name="group" table="gsgroup" primary="gid">
			<avoiddublicate>groupname</avoiddublicate>
		</table>
		
		<table name="usergroup" table="gsusergroup" primary="ugid">
			<foreign>group</foreign>
		</table>
 		<!-- /authentication tables -->
		
		<!-- 
			more custom table definitions
		-->
		
	</tables>
</configuration>
-----------------8<-----------------8<-----------------8<-----------------

The User Table
--------------
The user table stores the basic data of all users: user-name, user-id and 
password. Besides that other essential information are: realname, email,
created-date, recent-date and a set of user flags.

- user-id: the user-id is the primary key of the user table
- user-name: this is login name of the user
- password: the users password. Passwords will be stored in an encrypted 
  format, therefore they will be hidden from the administration users as well.
- created-date: this field contains a timestamp of the creation
- recent-date: everytime the user logs in, this timestamp will be updated
- email: The email-address of the user is required to contact the user (send 
  password, etc)
- flags: The flags represent the current state of the user-account. This 
  set-field must at least allow: 
  - deleted: removed accounts - even if it is possible to change the 
	configutation it is strongly recommended to "mark" users as delete instead 
    of removing them. 
  - new: for registered users
  - approved: the new account is approved by a system administrator (optional 
    but strongly recommended)
  - enabled: account is enabled
  
The group Table
---------------
The group table is quite simple, it basicly contains two fields: group-id and
groupname. Of course, the groupname must be unique. 

The Usergroup Table
-------------------
The usergroup table implements the relation between users and groups. Therefore 
it stores both, user-ids and group-ids. The default setup should be all right 
in most cases.

Additional Fields?
------------------
The base system including the build-in account manager as well as the user 
register tools require the above mentioned fields in the user table. Therefore 
the described tables is the minimal setup. 

If your application needs additional data for example in the user table, the 
framework will run fine with extended tables. The same for user-flags - you are 
allowed to expand the set-field if you need addtional flags. 

Of course, you are allowed to use addional fields in the group and usergroup 
table, too. 

SQL-dump
--------
See sql.txt, the sql-statements can be found in doc/sql/wbuser.sql. 

Permissions
===========
In order to use the authrozation features as well, see auth.txt.

User Managerment
================
Well, writing code is more exiting, than punching in manuals...

Automatic User Registration
---------------------------

User Account Administration
---------------------------