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
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.
- Open the 'Services' control panel.
- Stop the 'IIS Admin Service' - this will also stop the Web and FTP services on your machine.
- Open the 'Add/Remove Programs' control panel.
- Remove your old copy of 'ASPLogin'.
- Close the 'Add/Remove Programs' control panel.
- Run your new copy of the ASPLogin.exe installer.
- Start the 'IIS Admin Service', 'FTP Publishing Service' and 'World Wide Web Publishing Service' in the Services control panel.
- 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.
- 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).
- Run regsvr32 on asplogin.dll to register it as an ActiveX component.
- Create shortcuts in the Start menu to the ASPLogin documentation (this file), the license agreement and the ASPLogin Pro registration utility.
- Place a copy of the files asplogin.asp, aspldeny.asp and aspladmn.asp in your web root.
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 %>Or, in JScript:
<%
Set asplObj=Server.CreateObject("ASPL.Login")
asplObj.Protect
Set asplObj=Nothing
%>
<%@LANGUAGE=JScript%>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:
<%
asplObj=Server.CreateObject("ASPL.Login");
asplObj.Protect();
asplObj="";
%>
<% 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 %>Note: Group and date permissions work only in ASPLogin Pro and will be ignored in the freeware version.
<%
Set asplObj=Server.CreateObject("ASPL.Login")
asplObj.Group("management")
asplObj.Group("administrators")
asplObj.User("Fred")
asplObj.Protect
Set asplObj=Nothing
%>
Additional ASPL.Login object methods
An ASPL.Login object can also call the method
asplObj.ResetPermissionwhich 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>This example file sets the Session("asplConnStr") variable to point to an access database installed at C:\users.mdbOther 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:
Sub Session_OnStart
Session("asplConnStr")="DBQ=c:\users.mdb;Driver={Microsoft Access Driver (*.mdb)};"
End Sub
</SCRIPT>
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 sensitiveThe 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:
- 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.
- Add a line in each virtual server root's global.asa setting Session("asplConnStr") to point to the appropriate database for that server.
- Make copies of asplogin.asp, aspldeny.asp and aspladmn.asp under the virtual server root.
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. There is also a FAQ
section once you register at http://www.asplogin.com/support/asplogin.asp.
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 Technical Support on the ASPLogin website. Please be sure to include
your serial number in the subject line of the message.
Summary of all ASPLogin settings, forms, variables and methods
