ASPLogin v5.5
	ASPLogin v3.0
	ASPLogin

ASPLogin Documentation version 3.0

ASPLogin Documentation

ASPLogin comes in two flavors, a freeware version and a Pro 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 Pro license online at http://www.asplogin.com/purchase.htm

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)
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 database. You may use either the ready-made user database provided with ASPLogin, or use any other ODBC datasource. 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 schema 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-compatable web servers as well.

ASPLogin Pro offers additional functionality, such as: user and group level permission for individual documents, document expiration dates, logging, user activation/inactivation and user expiration dates.

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. Open the 'Services' control panel.
2. Stop the 'IIS Admin Service' - this will also stop the Web and FTP services on your machine.
3. Open the 'Add/Remove Programs' control panel.
4. Remove your old copy of 'ASPLogin'.
5. Close the 'Add/Remove Programs' control panel.
6. Run your new copy of the ASPLogin.exe installer.
7. Start the 'IIS Admin Service', 'FTP Publishing Service' and 'World Wide Web Publishing Service' in the Services control panel.

This procedure will not overwrite your existing ASPLogin user database.

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 and the software license agreement.
2. Place a copy of asplogin.dll (the server component itself) in the inetsrv subfolder of your system directory (C:\winnt\system32\inetsrv by default in Windows NT, C:\windows\system\inetsrv 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 files asplogin.asp, aspldeny.asp and aspladmn.asp 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 ulitity 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 asplogin.asp and aspldeny.asp in your web server root. 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 ASPLogin Program Files directory.

You may edit asplogin.asp and aspldeny.asp to match your site. Be sure, however, not to modify any of the ASP code in asplogin.asp before <HTML> or between <!--ASPLogin form begins--> and <!--ASPLogin form ends-->.

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

Note: 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).

The best place to set this information is in the file 'global.asa' in the root level of your site. An example global.asa is shown below.

<SCRIPT LANGUAGE=VBScript RUNAT=Server>
Sub Session_OnStart
Session("asplConnStr")="DBQ=c:\users.mdb;Driver={Microsoft Access Driver (*.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)

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 asplogin.asp, aspldeny.asp and aspladmn.asp 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.

Getting Help

Product and documentation updates are available at http://www.asplogin.com/support.htm. 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