File: readme.txt
Script Name: vAuthenticate 2.0
Author: Vincent Ryan Ong
Email: support@beanbug.net

Description:
vAuthenticate is a revolutionary authentication script which uses
PHP and MySQL for lightning fast processing. vAuthenticate comes 
with an admin interface where webmasters and administrators can
create new user accounts, new user groups, activate/inactivate 
groups or individual accounts, set user level, etc. This may be
 used to protect files for member-only areas. vAuthenticate 
uses a custom class to handle the bulk of insertion, updates, and
deletion of data. This class can also be used for other applications
which needs user authentication.

This script is a freeware but if you want to give donations,
please send your checks (coz cash will probably be stolen in the
post office) them to:

Vincent Ryan Ong
Rm. 440 Wellington Bldg.
655 Condesa St. Binondo, Manila
Philippines, 1006


==============================
 vAuthenticate 1.1 README FILE
==============================

Contents:
  * Introduction
  * Package content
  * Requirements
  * Upgrading
  * Installation
  * Administration
  * Usage
  * Change Log

~~~~~~~~~~~~~~~~~~~~~~~

* INTRODUCTION

  vAuthenticate is an authentication system which can integrate with any
  existing website that meets the requirements. It works well with 
  vNews and vPoll. vAuthenticate provides a gatekeeper wherein
  any user or admin must satisfy the password verification to either 
  log in (user) to a protected area or administer (admin) the
  vAuthenticate admin control panel.


    FEATURES:
    1. Flexibility
	= vAuthenticate allows administrators and webmasters to integrate it
	  with the current unprotected website. This is specially useful
	  if major changes are going to be painful. With vAuthenticate, you're
	  just one step towards getting the security you needed most.
    
    2. Speed
	= vAuthenticate uses the dynamic-duo of PHP and MySQL which enables
	  blazing fast transactions where only your server speed dictates 
	  the limit.
    
    3. Compactness
	= vAuthenticate is very small thus takes up little space allowing 
	  you more room to enhance your site's other features.

    4. User groups
	= vAuthenticate allows you to group your members into teams. Each team
	  has a team lead. vAuthenticate gives you the option to use such teams
	  just in case you need them although it would work even for simple 
	  sites which do not need such features. A powerful function of user
	  groups is its ability to give admins the chance to inactivate ALL
	  members in the group at once. No more modifying each record. Just 
	  imagine if there are a hundred members to inactivate!

    5. Portability
	= vAuthenticate makes use of a custom class called auth.php. This class
	  handles all the insertions, deletions, etc. of the system. This can 
	  be used with other PHP scripts even without the admin interface.


    6. Ease of use
	= vAuthenticate comes with a powerful administration interface that lets
	  site administrators and webmasters to control access to protected 
	  pages.


* PACKAGE CONTENT
  ** denotes required file

  auth.php - authentication class **
  authconfig.php - file and database configuration file **
  createdb.sql - database creation file **
  patch-2.sql - required update to version 2 (FOR USERS OF LOWER
	       VERSIONS ONLY WHO WANTS TO UPGRADE TO 2.0) **
  failed.php - page to display when login is incorrect
  sample.php - sample login interface
  success.php - page to display when login is successful
  page2.php - sample secured page. use direct access to test.
  check.php - file to include on top part of pages to secure. **
  vAuthenticate.php - result file that is opened after loging in. this file calls
		either the success or failed page upon login. **
  readme.txt - this file
  AuthClass.txt - Detailed class description for auth.php
  admin/authgroup.php - group administration file **
  admin/authuser.php - user administration file **
  admin/index.php - administration home page **


* REQUIREMENTS

  OS: Linux, Windows NT/2000/Whistler(XP) Server Family, Unix
  WEB SERVER: Apache (latest release)
  SCRIPTING: PHP 4 (latest stable release)
  DB: MySQL (latest stable release)
  DB MANAGEMENT: phpMyAdmin or any similar types of db manager
  BROWSER: Cookie-Enabled


* UPGRADING - This section is only applicable for people who has an 
	existing vAuthenticate installed in their server.

  1. Open your DB Manager and execute patch-2.sql. You are not required to 
	include patch-2.sql in your online folder since it is only needed
	once, during database schema upgrade. 

  2. Re-upload all the required files (see section: Package Content) except for
	*.sql files. If you want to retain the demo files (sample.php, failed.php,
	success.php), you'd need to re-upload them as well because of some
	changes.

  NOTE: Basically, this version massively changed auth.php, authuser.php, and
	authgroup.php. authconfig.php has been added an additional line to 
	support illegal access via direct method to a secured file. It is up to 
	you to decide whether you want to upgrade your existing installation
	or re-install this script. HOWEVER, it is highly recommended that
	you re-install from scratch since this is a major version release.


* INSTALLATION

  1. Open your DB Manager and execute createdb.sql. You are not required to 
	include createdb.sql in your online folder since it is only needed
	once, during database creation.

  2. Edit authconfig.php and set the values to reflect your host's
     	configuration. If you are going to use vAuthenticate out 
	of the box, it is recommended that you only edit the DB
	settings in the authconfig.php. Later on, when you are ready
	to deploy it in your site, edit the failed and success 
	paths in authconfig.php to reflect the path to your failed 
	and success pages.

  3. Edit auth.php and edit the lines with var such that it reflects 
	that of your web host. Note that this is the same with the 
	DB Settings in authconfig.php

  4. If you are going to use vAuthenticate in your existing site, be sure
	to take note of this:
	a. The file where your login page (the one with the username and 
	   password text box) should contain the include statement similar
	   to the ones found in sample.php.
	b. The form action should also be the same with that of sample.php
	   (which is vAuthenticate.php) because this calls the results page 
	   which in turn calls and makes use of the auth.php class
	c. The username text box MUST have name="username" and the password
	   textbox should have name="password". Take note of the case. All
	   names are in small caps. vAuthenticate will NOT work if you set 
	   the name of the username and password fields to any other name.

  5. It is worthwhile to note that since we use server side includes in 
	the results page (default: vAuthenticate.php), the success and
	failed pages might have to be edited to conform to the page call
	since it would be executing on the same directory with vAuthenticate.

  6. All files under the admin folder must remain that way. The admin folder
	itself MUST reside inside the folder where vAuthenticate is located. 
	Although you can change this in authconfig.php, it is not recommended
	to change the line unless you know a great deal about server side
	includes and pathname resolution.

  7. OPTIONAL: Edit check.php so that you can customize the look of the error
	message to display when an illegal access using direct method is used
	on files. Be sure to change only the HTML part of the file unless you know
	what you are doing.

  8. Upload in ASCII all required files (see Package Content for details) and
	non-required files (just in case you want to test the script) in any 
	directory as long as the success and failed pages are properly
	taken into consideration (see authconfig.php for path revisions). 



* ADMINISTRATION

  After installation, 2 new table named "authuser" and "authgroup"
  should have been created including the built-in users and groups.
  Follow the instructions below to administer vAuthenticate.

    LOGGING IN AS ADMINISTRATOR:
    1. Go the the login page of the website.

    2. Login as "sa" and enter the password. (Upon installation, the 
	password of user "sa" is a blank (not "blank").

    ADDING USERS
    1. After loggin in, click on Users in the top menu of the admin
	home page.
    2. Enter the details. Take note of messages which would be given
	by the system regarding your entry.
    3. If you have already entered a user or modified one but still
	want to enter another, click on the "Add New" button.

    MODIFYING USERS
    1. Click on the desired username on the user list found at the 
	right side of the user administration area
    2. Modify the information 
    3. Press Modify button to save changes

    DELETING USERS
    1. Click on the desired username on the user list found at the 
	right side of the user administration area
    2. Press Delete button to remove user
	 
    ADDING A NEW TEAM
    1. Either:
	a. Click on the link named Add beside the team drop-down list
	   in the user administration area
	
	OR

	b. In the admin home interface, click on the link Groups.
    2. Enter the info needed. 

    MODIFYING A TEAM
    1. Click on the desired team name on the team list found at the 
	right side of the team administration area
    2. Modify the information 
    3. Press Modify button to save changes
    4. Making a team inactive automatically makes ALL users in the 
	team to be inactivated

    DELETE A TEAM
    1. Click on the desired team name on the team list found at the 
	right side of the team administration area
    2. Press Delete button remove the group.
    3. Deleting a team automatically makes all members of the team 
	a member of Ungrouped.


* USAGE

  ALL records in the authuser table contains the following info:
	1. id (use $detail["id"] to get the unique id) - this is used for sorting
	   purposes only and can be used as an alternative primary key
	2. username (use $detail["uname"] to get the username) - this is the 
	   username of the member
	3. password (use $detail["passwd"] to get the passwd) - this is the 
	   password of the member
	4. team (use $detail["team"] to get the taem name) - this is the 
	   teamname of the member
	5. level (use $detail["level"] to get the level) - this is the 
	   level of the member
	6. status (use $detail["status"] to get the status) - this is the 
	   status of the member which can either be active or inactive
	7. lastlogin (use $detail["lastlogin"] to get the last login date and time) - 
	  this is a timestamp on the last lagin date and time of a member.
	8. logincount (use $detail["logincount"] to get count) - this is a 
	  counter which increments everytime a member/admin logs in.

  For example, refer to success.php and notice how it utilizes $detail["field"] 
	to get the info of the field. You may then perform level checking 
	for access restrictions depending on user level. But of course that
	is another story.

  You may use auth.php to automatically add users to the DB from your
	existing signup form. BUT, to do this, you would need to have an
	understanding of what auth.php returns for each transaction 
	you make. For more info regarding this, check out AuthClass.txt

  To secure pages, you would need to add the following lines on top of the pages
	you want to secure:
	
	<?
		include ("path/to/auth.php");
		include ("path/to/authconfig.php");
		include ("path/to/check.php");	
	?>

	where path/to/ refers to the path of the files relative to the current
	directory of the file being secured. For an example, please see 
	page2.php. If you haven' logged in yet or have logged in using a
	wrong username and password, you will get an Illegal Access 
	error on page2.php. However, if you have logged in successfully
	and without closing the browser, you tried accessing page2.php, 
	you'll notice that you can see the message (2 to 3 lines) in the file.

  One thing to note: Usernames of level 1 cannot browse secured pages. To be
    	be able to do this, it is recommended to create a new group called Browsers
	with new usernames that the admin users can use for browsing secured pages.
	vAuthenticate was made such that admin usernames are made specifically for
	security administration.
	

* Change Log
	version 1.1 - Changed .cls and .inc extensions to .php for a more
			secured script.
	
	version 2.0 - Session support.
		  - Security against direct access to secured files.
		  - Additional details available for users (Last Login and Login Count).
		  - Revised DB querying method to support latest PHP versions.


***********************
THAT's IT!
email support@beanbug.net for support.
***********************
