ASPLogin v5.5
	ASPLogin v3.0
	ASPLogin

ASPLogin Documentation version 1

ASPLogin Documentation

ASPLogin comes in two versions, a freeware version and a Pro 2000 version. We are committed to keeping the basic ASPLogin freeware product just that - free, however we are also trying to provide additional useful features for more demanding applications in response to your requests. These features are available in the Pro version only.

You can buy an ASPLogin 2000 Pro license online at http://www.asplogin.com/purchase.asp

Contents

Introduction
Installation
Preparing your web project
Enabling protection for your documents
Additional ASPL.Login object methods
Setting up the user database and login forms in global.asa
Web-based administration
Using ASPLogin with virtual servers
Who's logged in?
User Logging (Pro)
Data Prompts  
Automatic User Signup
Forgot Your Password
Cookies
Mass e-mail
User activation and expiration (Pro)
Getting Help
Summary of all ASPLogin settings, forms, variables and methods

Introduction

ASPLogin provides user authentication and management for Active Server Page (ASP) based web sites and applications.

ASPLogin uses an ActiveX server component to automatically send users to a login page, and then checks their authentication information and document permissions from a Microsoft Access 2000 database. You may use either the ready-made user database provided with ASPLogin, or use any other ODBC data source. ASPLogin also comes with a web-based administrator which can be used to setup users and groups in your ASPLogin database via a web browser. Both ASPLogin and the ASPLogin administrator are flexible enough to adapt to virtually any database scheme you currently use or choose to implement. 

ASPLogin works with ASP - your web site must reside on a server that can process ASP scripts, such as Microsoft Internet Information Server (IIS). ASPLogin is officially supported on Microsoft IIS4 or greater and Personal Web Server (PWS) 4 or greater, however it may work with other ASP-compatible web servers as well.

ASPLogin 2000 Pro offers functionality such as: user and group level
permission for individual documents, document expiration dates, user logging, user activation/inactivation, user expiration dates, additional user information can be stored, cookie to control login requests, automatic signup script, lost your password script, and customizable headers and footers. 

Installation

If you are upgrading from a previous version of ASPLogin, you must follow the following procedure to insure the replacement of your old copy of ASPLogin.

1. Create a backup of your database if it resides in C:\Program Files\ASPLogin.
2. Open the 'Services' control panel.
3. Stop the 'IIS Admin Service' - this will also stop the Web and FTP services on your machine.
4. Open the 'Add/Remove Programs' control panel.
5. Remove your old copy of 'ASPLogin'.
6. Close the 'Add/Remove Programs' control panel.
7. Run your new copy of the ASPLogin installer.
8. Start the 'IIS Admin Service', 'FTP Publishing Service' and 'World Wide Web Publishing Service' in the Services control panel.

ASPLogin Pro is distributed as a single self-extracting installer file. Running the installer will:

1. Create an ASPLogin program folder (by default in C:\Program Files\ASPLogin) with the default ASPLogin database, a registration utility to upgrade to the Pro features, the documentation, asp scripts, and the software license agreement.
2. Place a copy of asplogin.dll (the server component itself) in the system32 subfolder of your system directory (C:\winnt\system32 by default in Windows NT, C:\windows\system in Windows 9x).
3. Run regsvr32 on asplogin.dll to register it as an ActiveX component.
4. Create shortcuts in the Start menu to the ASPLogin documentation (this file), the license agreement and the ASPLogin Pro registration utility.
5. Place a copy of the asp scripts and images in your web root.

If you have purchased a single domain ASPLogin Pro license, you must enter your registration information into the ASPLogin administrator using a web browser (see Web-based administration). If you have purchased a multiple domain, single server license, you must enter your registration information using the ASPLogin Pro registration utility found in your start menu under Programs->ASPLogin.

Portions of ASPLogin require the Microsoft Visual Basic 6 runtime files and Data Access Components version 2. If you do not have these files installed, you can obtain them for free from Microsoft at http://support.microsoft.com/download/support/mslfiles/Vbrun60.exe and http://www.microsoft.com/data/mdac2.htm (ASPLogin requires only the minimal installation).

You may uninstall ASPLogin Pro using the Add/Remove Programs control panel.

Preparing your web project

Make sure that every HTML document you wish to protect with ASPLogin has the extension .asp, not .htm or .html. If you use a site management package, such as Microsoft FrontPage, you should be able to rename your files without breaking any links.

Your web server must be configured so that all the documents that you with to protect reside under one server root which has both read and execute or read and script permission.

The ASPLogin installer should have placed a copy of the following files in your web server root: (freeware versions only contain asplogin.asp, aspldeny.asp, and aspladmn.asp scripts)

aspladmn.asp

asplogin.asp 

aspldeny.asp

adovbs.inc

global.asa

lost_your_password.asp

lost-password-head.htm

lost-password-foot.htm

member_confirmation.htm

password_confirmation.htm

sign-up.asp

sign-up-foot.htm

sign-up-head.htm

/images/forgot_password.gif

/images/members_sign_in.gif

/images/not_a_member.gif

/images/password_head_at_top.gif

If it did not, or if you are setting up ASPLogin on a new virtual server, just make a copy of these files from the directory you choose to install them to.

You may edit asplogin.asp, aspldeny.asp, headers and footers to match your site. 

The sign-up.asp page has a few variables that need to be setup.  These variables are in the first 4 lines of the sign-up.asp. They are:

Const ADMIN_EMAIL="any@email.com"
Const EMAIL_SUBJECT="Website Membership"
Const SIGNUPGROUP="groupa"
Const LOGIN_PAGE="http://www.anydomain.com"

The ADMIN_EMAIL is the address that receives the e-mail each time a user registers and also the from address the users receive after they signup from your site.  EMAIL_SUBJECT is the subject of the e-mail message.  SIGNUPGROUP is the group in your database that the users are registering for.  You want to change this to reflect a group in your database.  Finally, LOGIN_PAGE is the page your users receive in the e-mail to log into your site.  Do not make this page asplogin.asp...You must specify the actual name of the page you want the user to log into.  As long as you have ASPLogin installed and configured for that page, your users will be prompted to login.

The same goes for the lost_your_password.asp script.  Here are the variables that need to be set in this script as well.

Const ADMIN_EMAIL="any@email.com"
Const LOGIN_PAGE="http://www.anysite.com"
Const EMAIL_SUBJECT="Lost Your Password"

ASPLogin will display an "invalid login" message on the login page if a user inputs a user name/password combination that is not in the database. You may customize the "invalid login" message by setting Session("asplLoginError") in global.asa (more on global.asa below). This is particularly useful for sites are not written in English.

If you are using ASPLogin Pro, you may also want to have specific documents for users whose accounts have expired or are inactive. To use these features, create HTML or ASP files for your expired and or inactive user pages and place them under your web server root. You will have to set session variables with the path to these files (see global.asa, below). If you do not set these extra files up, ASPLogin will just send expired or inactive users to aspldeny.asp by default.

Enabling protection for your documents

Each Asp file that will be protected by ASPLogin must have a small piece of ASP code at the start of the file - before any other HTML or server-side scripting. Microsoft ASP uses VBScript by default, however an example is also provided in JScript. The very top of your Asp files should read:

<%@ LANGUAGE=VBScript %>
<%
Set asplObj=Server.CreateObject("ASPL.Login")
asplObj.Protect
Set asplObj=Nothing
%>

Or, in JScript:

<%@LANGUAGE=JScript%>
<%
asplObj=Server.CreateObject("ASPL.Login");
asplObj.Protect();
asplObj="";
%>

By placing this code on your Asp files, users will automatically be sent to the login page (asplogin.asp) the first time they access one of the Asp files. After logging in, they will be able to go to any protected page without having to log in again during their site session. If they come back at a later date, they will be presented with the login page once again, regardless of which page they access first.

To manually log a user out of your site, they need to access a page containing the ASP script:

<% Session.Abandon %>

User, group and date expiration settings can be added in each document with the following directives, placed between the Server.CreateObject and Protect lines:

asplObj.Group("GroupName")

asplObj.User("UserName")

asplObj.LastDate("1/1/2001")

For example, to make a document available to all users in a group called 'management', members of a group called 'administrators' and a user called 'fred' (who may or may not be in either of the groups), you would add the following code to the top of the document:

<%@ LANGUAGE=VBScript %>
<%
Set asplObj=Server.CreateObject("ASPL.Login")
asplObj.Group("management")
asplObj.Group("administrators")
asplObj.User("Fred")
asplObj.Protect
Set asplObj=Nothing
%>

Cookies can be used so when users return within a specified period of time they will not be challenged for a login screen.  By Default this method is set to 7 days, you can change this in the global.asa :

     Application("COOKIE_EXP_DAYS") = 2

Note: Cookies, Group and date permissions work only in ASPLogin Pro and will be ignored in the freeware version.

Additional ASPL.Login object methods

An ASPL.Login object can also call the method

asplObj.ResetPermission

which clears all user, group and lastDate directives already set on the current page. This is useful only when you are running conditional permission code. Most ASPLogin installations will never use asplObj.ResetPermission.

Finally, ASPL.Login objects have a DebugInfo method which returns the version number and debugging information.

Setting up the user database and login forms in global.asa

ASPLogin Pro comes with a pre-made MS Access format user database.

ASPLogin must be able to find your database. If you have installed ASPLogin in the default location, the pre-made database is located at C:\Program Files\ASPLogin\asplogin.mdb on your server's hard disk.

If you installed to another location, or plan to use a different data source such as MS SQL Server, you must set ASP session variables to tell ASPLogin where to find the database, and what the table and column schema is (if different from the default).  We have provided you with a global.asa and two different methods to connect to your database.  

<SCRIPT LANGUAGE=VBScript RUNAT=Server>
Sub Application_OnStart

Application("COOKIE_EXP_DAYS") = 7

End Sub

Sub Session_OnStart

Session("asplConnStr")="Driver={Microsoft Access Driver (*.mdb)};DBQ=" & Server.MapPath("/database/asplogin.mdb") & ";"

End Sub
</SCRIPT>

This example file sets the Session("asplConnStr") variable to point to an access database installed at C:\users.mdb

Other ASPLogin session variables are available for changing the table and field names that ASPLogin uses to authenticate users and check group permissions. You only need to set these if you do not use the pre-made database, and you only need to set them once per session, as above. There are also session variables for the locations of documents to direct users to if their account is expired, if an error occurred with the login, etc. The complete set of ASPLogin settings session variables is in the following table:

Session Variable	What it sets
asplUserTbl	name of the table with user info
asplGroupTbl	name of the table with group names
asplMemberTbl	name of table that maps users to groups
asplUserTbluserid	autonumber or identity field for users
asplUserTblusername	field with user name
asplUserTblpassword	field with password
asplUserTblactive	Boolean (yes/no) for whether the user is active
asplUserTblexpires	last date that the user can log in
asplGroupTblgroupid	autonumber or identity field for groups
asplGroupTblgroupname	field with group name
asplMemberTbluserid	field in member table for userid
asplMemberTblgroupid	field in member table for groupid
Session("asplFormPath")	Path to asplogin.asp if not in the web server root
Session("asplDenyPath")	Path to aspldeny.asp if not in the web server root
Session("asplInactivePath")	Path to page for inactive users (default is aspldeny.asp)
Session("asplExpiredPath")	Path to page for expired users (default is aspldeny.asp)
Session("asplLogPath")	Windows path to user log file
Session("asplLoginError")	Error message to display when incorrect password or unknown user name is entered in asplogin.asp
Session("asplErrorPath")	Path to page for database errors during login (default prints a text message to the browser)
Session("asplUserDispTblStr")	Path to the table in the database for user preferences.

Web-based administration

The the web-based administration utility is installed by default as /aspladmn.asp under your web root. The administration utility is protected by ASPLogin like any other page in your site. Access to the administrator is initially restricted to the default user 'Admin', with the password 'Admin' in the ASPLogin pre-made database. You should change this user's password immediately when you first run the web administrator. Note that ASPLogin passwords are case sensitive

The web based administrator will let you add, edit and delete users and groups in your ASPLogin database. In addition, you can enter your registration information into the 'settings' tab to activate the Pro features.

Using ASPLogin with virtual servers

Follow the following steps to enable ASPLogin with more than one virtual server:

1. Make a copy of the default database for each virtual server (not necessary if you are using a different ODBC database for user names and passwords). You can name the database anything you like, e.g. site1.mdb, site2.mdb, etc. for different servers.
2. Add a line in each virtual server root's global.asa setting Session("asplConnStr") to point to the appropriate database for that server.
3. Make copies of your asp scripts under the virtual server root.

Any other ASPLogin settings or features can now be used in the virtual server. Remember that you must purchase and enter registration information into the administrator for each domain you wish to use the Pro features in. An ASPLogin multiple domain license is available to activate Pro features for all virtual servers on one machine.

Who's logged in?

ASPLogin sets the session variables Session("asplUserName") and Session("asplUserID") with the name and id number of the current logged in user. You can use these variables in your own ASP scripts to customize your site content for different users.

User activation and expiration (Pro only)

The active field of the ASPLogin Pro database (or any boolean or yes/no field in your own database) can be used to indicate whether users are permitted to log in to the site. If the active field is set to TRUE or YES then a user's login will be accepted. If the field is FALSE or NO, the user will be sent to aspldeny.asp. Alternatively, you can set the session variable Session("asplInactivePath") to an alternate file for inactive users.

The active field is useful for situations where users sign up, but then must wait until their credit card has been charged or other information has been received to access your protected pages.

Similarly, you may want certain users to only be able to access the site for a certain period of time. The expiration field allows you to set a date limit on any given account, after which they will not be able to log in. Just like the active field, if a user name has expired, the user will be sent to aspldeny.asp unless the session variable Session("asplExpiredPath") has been set to an alternate destination for expired users (such as a page to renew their membership).

User Logging (Pro only)

ASPLogin Pro can keep a log file of all the users who access protected files. ASPLogin Pro does not perform logging by default. To activate this feature, define the session variable Session("asplLogPath") in your global.asa file. The variable should contain the full windows path to the log file. If the file does not exist, it will be created. For example:

Session("asplLogPath")="C:\temp\asplogin_logfile.txt"

The log file is in W3C Extended Log File format, with the username substituted for the URL. This makes it easy to run the log files through many standard web access statistics packages to determine the number of logins, who logs on the most, when logins occur, etc.

Data Prompts (Pro only)

The web based administrator can select the fields that are to be displayed on the sign-up.asp page and also in the aspladmn.asp.  This will allow you to collect unique infomation about your users.  You also have the ability in the aspladmn.asp to change the names of the fields that the users are being asked.  This is done using the options
selection on the administrator menu. All field with a "Y" in the selected column will
be used for the administrators user entry screen.

 
Automatic User Signup  (Pro only)

ASPLogin 2000 comes with automatic user signup.  Users can come to your site and register for membership.  The questions that the users is asked for in the sign-up process are the data prompts specified in the aspladmn.asp.  After a user signs up at your site they will be directed to a confirmation page and they will receive and e-mail of their membership information.  You will also receive an e-mail.  The admin e-mail address and homepage that is sent to the user is configurable in the sign-up.asp page.

Const ADMIN_EMAIL="any@email.com"
Const EMAIL_SUBJECT="Website Membership"
Const SIGNUPGROUP="groupa"
Const LOGIN_PAGE="http://www.anydomain.com"

The ADMIN_EMAIL is the address that receives the e-mail each time a user registers and also the from address the users receive after they signup from your site.  EMAIL_SUBJECT is the subject of the e-mail message.  SIGNUPGROUP is the group in your database that the users are registering for.  You want to change this to reflect a group in your database.  Finally, LOGIN_PAGE is the page your users receive in the e-mail to log into your site.  Do not make this page asplogin.asp...You must specify the actual name of the page you want the user to log into.  As long as you have ASPLogin installed and configured for that page, your users will be prompted to login.

A header and footer have also been provided so you can customize the sign-up process to flow with the look of your site.

You can also modify the membership confirmation page.

  

Forgot Your Password  (Pro only)

If users forget their password they can use this tool.  Upon entering the e-mail address they register with they will receive an e-mail with username and password information.  

For easy integration into your website we have also included a header, footer, and confirmation page you can edit.  These are the variables that need to be changed in the top of the forgot_your_password.asp script.

Const ADMIN_EMAIL="any@email.com"
Const EMAIL_SUBJECT="Website Membership"

Cookies (Pro only)

The Pro feature to write a cookie and control the login of the user is controlled 
by a variable in the global.asa file. The default for the cookie is 7days. If you
do not want to write cookies and have the user login each time set the variable
to zero. With the cookie set to 7 days any user that logs in within 7 days of the
previous login will not be challenged for a login. Insert this line in your global.asa
to control the cookie expirations days: Application("COOKIE_EXP_DAYS") = 7 

Mass e-mail (Pro only)

Mass e-mail allows can be found in the aspladmn.asp.  This utility allows you to send out e-mails to your website users.  You can choose to send e-mails by demographics and by the data prompts that you have setup.  Using a "%" (without quotes) in any format, either in the middle of text, before text, after text, or even standalone will help you in searching for your users e-mail addresses.

Getting Help

Product and documentation updates are available at http://www.asplogin.com/support/support.asp. There is also a FAQ. Please check there first if you experience any difficulties.

E-mail technical support is available to registered users of ASPLogin Pro - there is no support for the freeware version. Registered users can send support questions to v5support@asplogin.com. Please be sure to include your serial number in the subject line of the message.

Summary of all ASPLogin settings, forms, variables and methods