ZmeY ISAPI Authenticator version 1.5
ISAPI custom authentication filter for Microsoft
Internet Information Server 4 or later.
Contents of this document
How to install
Entering your serial number
Important notes to remember
User management tool for your customers
This package contains following files:
||ISAPI filter for Microsoft Information Server 4.0 or later. It
handles authentication requests from users as configured in its configuration file - see
||CGI application for ISAPI filter administration (includes
functionality of the client version).
This tool must be placed in some IIS virtual directory/site and must be accessible only
for the server administrators. Configure your server to ask for authentication while
accessing this file. Site can be any.
||CGI application for User database management for a particular site
only. Place this CGI in the administrative directory of your hosting customers. It must
reside in the site which will be managed through it !
||Empty configuration file. Copy this file in the persistent location,
do not share it to the WEB and enter its full path and file name when initially
||HTML Help file - documentation
||Utility for password change - can be exposed to the site users.
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
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 !
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
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).
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.
1.You have site www.alpha.dom listening on IP address: 22.214.171.124. Suppose that this
site is not accessible through another IPs or DNS names. You will need to add two
www.alpha.dom -> some authority
126.96.36.199 -> 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
- Filter receives username and password passed by WEB browser.
- Filter searches user in authority defined by bindings for
the current site (by IP or DNS name - Host header)
- If user was not found it logs error and returns HTTP error (Access denied).
- If user was found but user's account was disabled filter denies access.
- 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
- 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
- If Account was disabled filter denies access immediately. This causes non-mapped to NT
users accounts too.
- 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.
- 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
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: email@example.com
Extended authentication filters are planed - look at our site for more information.
Copyright © ZmeY soft 1999 - 2000