ISAPI custom authentication filter for Microsoft Internet Information Server 4 or later.

Contents of this document

Package contents
How to install
Initial configuration
Entering your serial number
Normal usage
Important notes to remember
User management tool for your customers

Package contents

This package contains following files:

Installation

It is simple to install filter and administrative tools - ISAPI filter must be placed somewhere and registered as filter in IIS. Use Microsoft Management Console and open Internet Information Server for your machine. Click properties, then choose WWW service and go to tab ISAPI Filters. Click Add button and browse for Authenticator1.dll or directly type path to it. Filter name field is not meaningful - type there pretty name of your choice. After all you will need to restart your Internet Information Server - to do so execute on command prompt these two commands:
net stop w3svc
net start w3svc

Initial configuration

Filter was installed but now you must configure filter options like configuration file, backup directory, your serial number and so on. To do this you must use CGI application AUTHADMINCGI.EXE. Place it in some place shared as virtual directory of a WEB site - you can create such directory or choose to copy this application somewhere in your administrative WEB site. Administrative application works without any pre-configuration - after copying it to desired location open your browser and go to the URL that points to it. For example www.admin.mycompany.com/tools/AUTHADMINCGI.EXE. This virtual directory must have execute access - not only script access (change this setting if needed) and site must require authentication - you will not be able to set serial number,configuration file and backup directory unless you are not authenticated as administrator. First time you refer administrative tool it will generate an error that means that there is no configuration file and will ask you to enter path to it. Copy empty configuration file in the permanent location (do not expose this directory to the WEB!) and enter full path and file name in the form.  Backup directory is optional and you can leave it empty at this time - if you choose to fill this field - choose empty directory because authenticator filter will backup its configuration (including entire user database) after each change !

Registration

Place your registration number (if it is wrong - filter will not work, but administrative tool ignores serial numbers). To do so in the AUTHADMINCGI.EXE menu choose General options (You must be authenticated as user with administrator privileges !).

Note: There is no installation because of configuration differences between WEB servers - we can not determine what site and virtual directory to use for admin tools . In addition your advanced administrators may want to install filter not for all sites. Pay attention of administration tool security - it must be accessible only for server administrators (and potential authorized persons).

Usage

After installation you will need to configure log file name - it will be appended with authentication events. And configure filter to handle some of your sites through specified authorities. How to do this:

Authorities: To create authority just click Add authority and give name to it. You can create more than one authorities - User data bases that will be used to authenticate users coming to your virtual sites. Any user manipulation must be performed over certain authority - and administrative tool will ask you to choose one if you are trying to add/delete/change user data. Important option is "Expiration required" checkbox found in the "add authority" and "edit authority" forms. Option specifies what filter will do if expiration date is empty for a particular user. If checked it will deny access otherwise access will be granted without date checking.

Bindings: To operate over a given site authenticator needs to know what authority to use on it. You must add appropriate bindings. Every binding defines connection between DNS name or IP address and authority. To define a binding you will need to enter in Add binding form DNS name or IP address of the site and select one authority. Virtual sites can be made in many different manners - and you must know how your sites work.

Some examples:

1.You have site www.alpha.dom listening on IP address: 234.1.1.1. Suppose that this site is not accessible through another IPs or DNS names. You will need to add two bindings:

www.alpha.dom -> some authority
234.1.1.1 -> same authority

2.If your site is accessible through more names - such as alpha.dom and www1.alpha.dom you will need to add these bindings too -

alpha.dom -> same authority
www1.alpha.dom -> same authority

If your virtual site answers only by checking Host header it is enough to add binding between site name and appropriate authority.

Users: User authentication works as follows:

1. Filter receives username and password passed by WEB browser.
2. Filter searches user in authority defined by bindings for the current site (by IP or DNS name - Host header)
3. If user was not found it logs error and returns HTTP error (Access denied).
4. If user was found but user's account was disabled filter denies access.
5. If user was found - filter checks for MapTo option specified. If this option was not specified filter passes authentication process to the IIS (respectively to the NT authentication services). If MapTo was set filter continues to the next step.
6. Password and expiration date checking goes on - on failure HTTP error will be generated (Access denied) else filter goes to the next step.
   • If "Account does not expire" is checked expiration date will not be checked
   • If expiration date is empty and "Account does not expire" is not checked filter will grant access depending to the default authority policy. If you checked "Expiration required" in the authority options access is denied otherwise granted.
   • If Account was disabled filter denies access immediately. This causes non-mapped to NT users accounts too.
7. If authentication was successful filter passes to the IIS username and password of NT account specified in the MapTo field.

NT accounts: NT accounts are used for user mapping. You can use these accounts to set filesystem security and give access to the some parts of a site only to users mapped to specific NT account. It is recommended to create several accounts and use them as groups for your WEB users. Only users with unchecked MapTo option are authenticated directly by your server - this option is good (and required if they use client admin tool) only for the site owners (your customers) or site administrators.

Finally ...

• You need to create bindings to define what authority to use for each handled site (if there is no binding site will not be handled by filter).
• You will need to create some authorities - probably one authority for each secured site. But you can use one authority for several sites.
• You will need to configure several NT accounts used for "real" file system security and use them for MapTo fields during WEB users management.
• Add some users to the the authorities. Specify mapping to the NT account for every user.
• If you need to give special access to some persons (probably owners of the hosted site) create (or use existing) NT account for these persons and add them to the authority used for this site, uncheck MapTo check box for them. Thus site owners are authenticated by NT authority (see below for more notes).

Special tool for WEB hosting customers

AUTHMANCUSTOMERCGI.EXE is a special tool that can be accessible through the web to the customers of your WEB hosting services. For example create virtual directory in this site and place tool there. Fix file security to restrict access of WEB normal users and tell URL to your customers. This tool will determine what authority to admin by the site bindings and will expose this authority to the customer. It gives add/delete/change user features.

Note that customer that will mange himself site users must be specified in this authority with unchecked MapTo field. If not you will need to create NT account with such privileges (used for admin tool security) and map All site owners to it.

Additional recommendation: (This causes not only usage of this filter)
Make your WEB site hosting customers members of one group and restrict access to the AUTHMANCUSTOMERCGI.EXE with it. This directory can be one for all, but it must be mapped as virtual directory with execute access in every customer's site !

If you have any questions and suggestions please mail us: support@zmey.com

Extended authentication filters are planed - look at our site for more information.

Copyright © ZmeY soft 1999 - 2000