vSignup 2.5 Documentation

Contents:
1. Introduction
2. Package Contents
3. Requirements
4. Upgrading
5. Installation
6. Administration
7. Usage
8. Demonstration
9. FAQ's
10. Changelog
11. Copyright Notice
12. Support Information

Introduction:

vSignup is a member registration script which utilizes vAuthenticate for its security handling. This handy script features email verification, sending confirmation email message, restricting email domains that are allowed for membership, and much more.

vSignup is an offshoot of what vAuthenticate can do. It provides a member-signup form which integrates well with vAuthenticate to create a powerful signup-and-authentication system for your site.

FEATURES:

1. Speed - vSignup uses the dynamic-duo of PHP and MySQL which enables blazing fast transactions where only your server speed dictates the limit.

2. Compactness - vSignup is very small thus taking up little space allowing you more room to enhance your site's other features.

3. Authentication Settings - vSignup allows you to configure whether the system will automatically approve new membership request or not. It also allows you to turn the email notification on or off. You also have the option to let the system send the admin an automatic email message everytime a new member signs up.

4. Email Verification - vSignup provides a standard email verification function to ensure that the email address specified in the field is valid in terms of format.

5. Email Confirmation Message - vSignup can sends out a confirmation email to the visitor who signed up to make sure that the email address he/she specified is really his/hers.

6. Restriction on Email Domains - vSignup allows you to restrict the people who signs up for membership by validating that their email address is in your list of allowable domains.

7. Emailer Profiles - vSignup allows the you to enter multiple Emailer profiles. These profiles allow you to set some predefined email messages to send to members during confirmation so that there will be a variety of templates to choose from.

8. Password Reminder - vSignup can rest a member's password in case they forget it.

Package Contents:

Filename	Description
auth.php	Authentication class
AuthClass.txt	Detailed class description for the auth class
authconfig.php	vAuthenticate path and database configuration file
check.php	Permission checker on all secured files
chgpwd.php	Change password utility for members
confirm.php	Email confirmation file
createdb.sql	MySQL table and initial data file
documentation.html	This document
failed.php	Failed login page
faq.txt	List of frequently asked questions and its corresponding answer
login.php	Sample login area (we suggest that you use your own design)
logout.php	Logout script which destroys the current session
process.php	Signup processor
pwdremind.php	Password reminder utility for members
README.txt	Contains the copyright and the initial notes for this script
signup.php	Sample signup form (we suggest you use your own)
signupconfig.php	vSignup path and database configuration file
vAuthenticate.php	This is the result file that is checked upon every login attempt. This will forward users to the proper success page that they should go.

admin/authgroup.php	Group administration area
admin/authuser.php	User administration area
admin/emailer.php	Profiles administration area
admin/index.php	Administrator home page
admin/settings.php	Script settings area
admin/userdetail.php	User details administration area for managing other user information

members/bygroup.php	Sample authentication based on member's group/team
members/bylevel.php	Sample authentication based on member's level
members/index.php	Sample member home page
members/page2.php	Sample member page used for direct access
members/userdetail.php	Member details page for modification (first name, last name, email, etc.)

Requirements:

Operating System: Linux, Windows NT/2000 Server Family, Windows XP, Unix
Web Server: Apache (latest release) with mail() function enabled
Scripting: PHP 4.3 above (magic quotes for MySQL recommended to be turned on) [This is NOT yet tested in PHP 5.x]
Database: MySQL (latest stable release)
Database User Interface: phpMyAdmin or any similar types of db manager
Browser: Cookie-Enabled; Javascript-Enabled

Upgrading:

Upgrading is not really recommended from any lower version of vSignup to this latest version of vSignup due to the drastic schema and business logic changes. if you are running on a previous version of vSignup, it is suggested that you backup your MySQL database or at least the tables associated with vSignup and then re-import the data one table at a time to the new vSIgnup tables. Take note that the password field for the authuser table has changed to 32 character-width and is in an encrypted form. The suggested approach is to clear out the value for the password once you import the old authuser data to the new authuser table. After doing this, execute the following statements in your database user interface such as phpMyAdmin:

UPDATE authuser SET passwd=MD5('access') WHERE uname='sa' OR uname='admin'

The above statement should set your sa and admin users' password to the proper form. Login to vSignup after this and change each member's password one at a time at the vSignup User Administration page. This should encrypt each member's password using MD5.

Installation:

1. Launch your database manager (phpMyAdmin) for MySQL and run the createdb.sql file.

2. Modify authconfig.php to match your database settings and your file pathing.

3. Modify auth.php to match your database settings.

4. Modify signup config to match your database settings, file pathing, and administrator email address.

5. You can modify the login.php page to suit your needs or better yet, use your own page and include a login box. One of the rules is that you SHOULD include the authconfig.php in whichever page you will have your login box at (let's say, your index.php). Also, take note of these requirements for the login box:

a.	The page where the login box is located should be a PHP file, not an HTML file.
b.	Login box's form action parameter should be set to <?php echo $resultpage; ?> as it gets the value from the authconfig.php that we included.
c.	The username field should have a name of 'username' without the quotes.
d.	The password field should have a name of 'password' without the quotes.

6. All files under the admin folder must remain that way. The admin folder itself MUST reside inside the folder where vSignup 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. The members directory can be anywhere as vSignup allows you to protect files outside the vSignup folder as long as the protected file is a PHP file and it has proper pathing for the 3 include files (auth.php, authconfig.php, andcheck.php).

8. Upload all files to your server using ASCII. You can disregard createdb.sql (we have already used it in step 1), README.txt, documentation.html, AuthClass.txt, and faq.txt as these are not used in the script itself.

Administration:

After installation, 5 tables will be created in your database. These tables are: authuser, authteam, emailer, signup, and signupsetup. To administer vSignup, do the following:

	Logging in as an Administrator
	1. Pull up the login page and login using either sa or admin for the username
	2. Enter 'access' without the quotes for the password
	3. Click on the Login button

	Setting up the script features *
	1. Click on the Settings link on the top menu
	2. Set the radio buttons depending on how you want to control the activation and emailing of notices
	3. Select an Emailer Profile to use for the notification (assuming you set the system to automatically send notification email)
	4. Enter a list of valid email domains in the text area. This is normally used for intranets or small group of people who don't want to open up the signup process to the whole internet community.

	Maintaining Users
	1. Click on the Users link on the top menu
	2. To add a user, enter the details and click on Add
	3. If you have already entered a user or modified one but still want to enter another, click on the "Add New" button.
	4. Once you have saved the user, the User Details link will show beside the team field. Click on this to add user details such as first name, last name, email, country, and zip code.
	5. To modify user details, click on the user on the list at the right-hand side of the page. This will pull up the user data and you can modify it. The password field will be set to blank as it is encrypted. If you need to change the password, enter the new password there, if not, leave it blank and it will retain the old password.
	6. To delete a user, just select a user from the list and then when the details are in the left-hand area, click on the Delete button.

	Maintaining Teams/Groups
	1. Click on the Groups link on the top menu
	2. To add a group, enter the details and click on Add
	3. If you have already entered a group or modified one but still want to enter another, click on the "Add New" button.
	4. To modify group details, click on the group name on the list at the right-hand side of the page. This will pull up the group data and you can modify it.
	5. To delete a group, just select a group from the list and then when the details are in the left-hand area, click on the Delete button. Any user assigned to the deleted group will be assigned to the Ungrouped group.
	6. If you inactivate a group, you also inactivate all users in the group.

	Setting up Email Profiles
	1. Click on the Emailer link on the top menu
	2. To add a new profile, enter the details and click on Add
	3. If you have already entered a group or modified one but still want to enter another, click on the "Add New" button.
	4. To modify profile details, click on the profile name on the list at the right-hand side of the page. This will pull up the profile data and you can modify it.
	5. To delete a profile, just select a profile from the list and then when the details are in the left-hand area, click on the Delete button. You can delete any profile except the Password Reminder.
	6. The name value will appear as the sender name in the actual mail while the email value will appear as the sender's email address when the member receives your mail.

* IMPORTANT:
There are 3 interrelated fields in the Settings page:
1. Automatically activate membership upon signup - This will set the member's status as active or inactive. If set to inactive, the administrator must manually activate the user UNLESS the user has an email notification that has the confirmation link URL.
2. Send email notification after signing up - This will trigger an email to be sent to the new member. The email that will be sent would depend on the default profile selected.
3. Choose default profile if sending email notification - This is the default email that will be sent to the new member ASSUMING that the the system is set to send email notification after signing up. This default profile may or may not contain the confirmation link URL needed to allow the user to activate their membership.

Because of this interralationship, it is recommended that if membership is NOT set to be activated automatically, "Send email notification after signing up" should be set to Yes and the default profile should be something that has the confirmation URL in it (via the [[CONFIRM]] key. Any other combination for the said scenario might result in a logic flaw and the administrator will have to activate each member manually.

Usage:

Although vSignup works out of the box, it is more likely than not that you will need to make some modifications to the code to match your needs. As such, you will need to have some knowledge on PHP, specifically on condition statements.

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 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:

<?php
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 must add some more PHP code for that. Please refer to the demo users for more information.

Some files you can directly link to from your website are:
1. signup.php (unless you have a different signup form)
2. members/userdetail.php (assuming the user is logged in, they can change their details here)
3. login.php (unless you have a different login form - like if it is in your index.php)
4. logout.php (you can check out the code and use it in your own logout page)
5. chgpwd.php (assuming the user is logged in, they can change their password here)
6. pwdremind.php

IMPORTANT:
vSignup uses a slightly-modified version of vAuthenticate. If you want to use vSignup in your site but you already have vAuthenticate installed, you would have to remove the current install of vAuthenticate before installing vSignup. After you install vSignup, you can then use the vAuthenticate that comes with it.

Demonstration:

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" without the quotes
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.

FAQ's:

Please refer to the faq.txt file included with the vSignup 2.5 package.

Changelog:

version 2.5
- Added default group option in signup settings
- Added default level option in signup settings
- Changed authteam table structures to accommodate new password length
- Used vAuthenticate 3.0.1 (which fixed some undefined index bugs)
- Fixed bug on the possibility of inactivating the sa and/or admin user accounts
- Used MD5 for password encryption instead of MySQL's password() function
- Allowed sending of information to email using templates
- Fixed error detection in Emailer administration
- Added character checking for "'" in auth.php's functions as an anti-SQL Injection measure
- Changed admin/authuser.php to accomodate new error messages in auth.php for apostrophe character in the username and password fields
- Fixed confirm.php's line 46 - extra open parenthesis
- Password Reminder moved from process.php to pwdreminder.php
- Changed Password Reminder email template
- Added random password generation for password reminder
- Changed vAuthenticate.php to allow global scope for session cookies
- Changed vAuthenticate and admin files to check group instead of level for consistency and clarity
- Changed substr_replace usage of process.php to str_replace to get rid of the loops which might affect performance.
- Changed pwdremind.php to replace strings that are keys according to the template set
- Added User Details page to allow administrators to change user details like first name, last name, email address, country, and zip code
- Added dynamics link to User Details page in authuser.php. If username on authuser.php is blank, link will not show.
- Changed table schema allowing NULL value for the datejoined field specifically for user details added on a different date (for those users added via admin area instead of signup form)
- Changed members/index.php to accommodate link for user details
- Fixed some typographical error in AuthClass.txt

version 2.1
- 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 where on previous versions of vSignup, 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
- Modified authuser.php to avoid passing all user details via GET method when editing the account
- Added Password Retrieval function.
- Added vSignup settings for administrator.
- Added Emailer Profiles.
- Revised DB querying method to support latest PHP versions.
- Consolidated the 2 DB creation script into 1.

Copyright Notice:

This script is free for your use. It does not have a licensing agreement yet but future releases will be aligned with the MIT License (which still makes the script free but with a more defined agreement).

If you want to give donations, please send your cheques to:

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

Support Information:

Please refer to the faq.txt file first before sending me an email as most issues that need clarification are answered there. If your problem is not on the said file, feel free to send a support email to support@beanbug.net.