Location: PHPKode > scripts > vAuthenticate Script > vAuthenticate/README.TXT
File: readme.txt
Script Name: vAuthenticate 3.0.1
Author: Vincent Ryan Ong
Email: hide@address.com

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 3.0.1 README FILE
==============================

Contents:
  * Introduction
  * Package content
  * Requirements
  * Upgrading
  * Installation
  * Administration
  * Usage
  * Demo
  * On future releases
  * FAQ's
  * 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 control access to protected 
	  pages.


* PACKAGE CONTENT
  auth.php - authentication class 
  authconfig.php - file and database configuration file 
  createdb.sql - table creation file 
  patch-301.sql - required update to version 3.0.1 (FOR USERS OF ANY VERSION BELOW
		3.0.1)
  failed.php - page to display when login is incorrect
  login.php - sample login interface
  logout.php - logout file used to close the current session
  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
  faq.php - list of frequently asked questions and the corresponding answers
  AuthClass.txt - Detailed class description for auth.php
  chgpwd.php - file to allow members to change their password
  admin/authgroup.php - group administration file 
  admin/authuser.php - user administration file 
  admin/index.php - administration home page 
  members/index.php - page to display when login is successful
  members/page2.php - sample secured page. use direct access to test
  members/bygroup.php - sample page security on a per-group basis
  members/bylevel.php - sample page security on a per-level basis


* REQUIREMENTS
  OS: Linux, Windows NT/2000 Server Family, Windows XP, 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; Javascript-Enabled


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

  1. Open your DB Manager and execute patch-301.sql. You are not required to 
	include patch-301.sql in your online folder since it is only needed
	once, during database schema upgrade. This patch is needed because the
	value contained in this field would be encrypted with MD5 encryption which 
	needs 32 character-spaces for storage.

  2. Re-upload all the files (see section: Package Content) except for
	*.sql files.

  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 login.php. 
	b. The form action should also be the same with that of login.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. Unlike the previous versions of vAuthenticate, starting from version 2.8, 
	vAuthenticate.php makes use of Javascript redirection instead of
	PHP include statements to point the user to the proper page.

  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 all files (see Package Content for details) in ASCII to 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 all users is "access")

    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. If you leave the password field blank,
	this will mean that you don't want to change the member's 
	password. If you enter something in the password field,
	this will be the member's new password.
    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. Click on the Groups link on the top menu.
    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 $check['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 $check['uname'] to get the username) - this is the 
	   username of the member
	3. password (use $check['passwd'] to get the passwd) - this is the 
	   password of the member
	4. team (use $check['team'] to get the team name) - this is the 
	   teamname of the member
	5. level (use $check['level'] to get the level) - this is the 
	   level of the member
	6. status (use $check['status'] to get the status) - this is the 
	   status of the member which can either be active or inactive
	7. lastlogin (use $check['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 $check['logincount'] to get count) - this is a 
	  counter which increments everytime a member/admin logs in.

  For example, login to the members area as a member and you'll see that there
	there are 2 examples provided. One is to restrict by level and the
	other is to restrict by group.

  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_once ("path/to/auth.php");
		include_once ("path/to/authconfig.php");
		include_once ("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.

  Take note that adding those "include lines" on top of your secured pages only 
	facilitate in checking of the username and password combination stored
	in the cookie. This is to protect it from direct file access. If you want to add 
	the necessary authentication code that takes note of the rules
	(for example, only level 4 members can access this page; or only
	members from the Friends group/team are allowed to see this page) that 
	you've made to be available in this file too, you would have to add something
	like the following on top of your secured pages:

	<?
		include_once ("path/to/auth.php");
		include_once ("path/to/authconfig.php");
		include_once ("path/to/check.php");	

		// Check for permission to view this page
		if ($check['level'] != 4)
		{
			print "<font face=\"Arial\" size=\"5\" color=\"#FF0000\">";
			print "<b>Illegal Access</b>";
			print "</font><br>";
  			print "<font face=\"Verdana\" size=\"2\" color=\"#000000\">";
			print "<b>You do not have permission to view this page.</b></font>";
			exit;	// Stop script execution
		}
	?>

  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.
	

* DEMO
  Here's a little something to let you test out and learn how to restrict access to pages
	on a per-group or per-level basis.

	1. Login as "sa" or "admin"
	2. Notice that there are usernames called G1-0001, G1-0002, etc.
	3. Click on these and take note of the team they are a part of and their level.
	4. For you to remember them easily, a convention was used for the usernames.
		G1-0001 stands for the first user under Group 1.
		G1-0002 stands for the second user under Group 1.
		G2-0001 stands for the first user under Group 2.
		... and so on ...
	5. Logoff as "sa" or "admin"
	6. Login as any of the users (except sa, admin, and test). Take note that their
		password is by default, "access" (unless you change them of course)
	7. You will be taken to the members' index page. Here, you'll see 2 links for
		demo purposes.
	8. Depending on the user you logged in with and the credentials that come with
		that user, you might or might not see the intended content for 
		the bygroup.php and bylevel.php.


* ON FUTURE RELEASES
  Below is a list of much-awaited features which was either emailed to me as a bug
	or as a script suggestion. Neither of these are guaranteed to be on the next 
	release though. I do make sure to address all concerns... specially bugs.

	1. Use of addslashes() and stripslashes() for fields being sent to MySQL
	2. Disallow multiple logins to the system 
	3. Encrypted username and password for cookies
	4. Paginate user and group list in administration interface
	5. Make administration interface more pleasing to the eyes (hehe)
	6. Make some demonstration area
	7. Add a new function to the auth class which will give us the list of currently
		online users and the total logged-in user count 
	8. Add an optional expiration date field for user accounts
	9. Remove the process of editing numerous lines in authconfig.php by creating
		an installer of some sort


* FAQ's
  Please refer to faq.txt


* 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.
	
	version 2.8 - Removed empty line in auth.php which causes an error on some web
			servers
		  - Added logout functionality
		  - Used javascript redirection in vAuthenticate.php to preserve original
			pathing of links on secured page
		  - Fixed a major bug in the admin area. Details are:
			On previous versions of vAuthenticate, assuming a user has 
			successfully logged into the members area, if he knows the URL
			to the admin pages (specially authuser.php and authgroup.php)
			he can have access to those pages.
		  - Added security to admin area
		  - Easier navigation in the admin area
		  - Added functionality to allow members to change their own password
		  - created a members directory in the package to make it more organized
		  - modified authuser.php to avoid passing all user details via GET method
			when editing the account

	version 3.0 - Added support for register_globals that are turned off by default
		  - Password is now encrypted upon addition of member
		  - Added 2 sample pages which would demonstrate how to restrict by
			group or by level
		  - Used more efficient code by eliminating previously recommended
			conditional statements for secured files. Introduced the use of
			include_once which would make code execution a little bit faster
		  - Modified code to limit the use of double quotes for array values and other 
			stuff. This is another small step in providing a secure script.
		  - Modified auth.php class' "modify" function to accommodate flexibility in
			modifying existing password for members
		  - Added support for websites based on an IP address instead of a domain
			name
		  - Added a couple of usernames and password with various groups and levels
			used for demonstration.

	version 3.0.1 - Fixed notices for undefined indexes
		  - Fixed sample page (bygroup.php) condition statement
		  - Modified auth.php class' "add user" to restrict on blank password for users being
			created
		  - Changed password field's structure to accommodate 32 characters for MD5
			encryption
		  - Changed encryption from MySQL's password() function to MD5
		  - Restricted inactivation of "sa" and "admin" users


*****************************************
THAT's IT!
email hide@address.com for support.
*****************************************
Return current item: vAuthenticate Script