Authenticator is an add-on filter to the Microsoft IIS web server that provides basic authentication against Microsoft Access, Microsoft SQL Server and MySQL Server data sources. This means that the standard client authentication dialogs can be used for authentication without requiring user licenses for accounts in Active Directory in Windows.
The filter has been tested successfully on:
- Windows XP Professional
- Windows 2000 Professional
- Windows 2000 Server
- Windows Server 2003
License
This application is provided free of charge for personal use. If you like it I would appreciate if you would link to my web site (http://www.spotwise.com).
Installation
Add the database as a data source as a System DSN in the Data Sources (ODBC) applet in the Control Panel. Database templates are provided for Microsoft Access, Microsoft SQL Server and MySQL Server. Choose the one that suits your purposes the best and add suitable user accounts to the database (check below).
Install the filter on a web site in the IIS snap in and set the security settings on a virtual directory below the web site to disallow unauthenticated access and instead use basic authentication. Although the filter requires the username/password to be sent in clear text it is be possible to use it in conjunction with SSL to encrypt the data over the network. Set the RequireSSL registry value to true if you want to prevent cleartext passwords to be sent over the network. Also, set the realm; the text will be shown in the authentication dialog if supported by the client operating system.
When first loaded by IIS, the code will write default registry settings. Start regedit and make changes under HKLM \ Software \ Bergek \ Authenticator.
Note: As always, be careful when changing the registry as mistakes can, at worst, render the computer unbootable.
- ConnectionString [SZ] – The connection string used to connect to the data source. In its simplest form it is just “DSN=Authenticator” (with Authenticator configured as the data source name in the control panel), although it can be formatted in various ways. The data source must be added as a System DSN since the user which will access it will most likely be the IUSR_{computer} account.
- SqlStyle [DWORD] – Controls the SQL style used to query the ODBC data source. Possible values are 0:Microsoft SQL Server, 1:Microsoft Access and 2:MySQL Server. By default MySQL Server syntax is used.
- RequireSSL [DWORD] – If set, the filter will return HTTP 401 Access denied if a request is made using non-encrypted HTTP. The HTTP 401 response is sent before the client has sent the user credentials which means that they will not be transmitted in cleartext form on the network.
- MappedLogin [SZ] – A valid user name on the computer. Accesses against the virtual directory will be mapped against this user which must exist and be allowed to access the resource in the web application. The user name should be provided in the form {domain}\{login} but it can be {login} only if the default domain is set in the IIS snap in. If your computer is not in a domain you should write the account as {computer}\{login}
- MappedPassword [SZ] – The password for the user account selected above. When the filter is first accessed this password will be encrypted and the encrypted version will replace whatever you type here.
- LogSuccesses [DWORD] – If set to true (non-zero), authentication successes are written to the database.
- LogFailures [DWORD] – If set to true (non-zero), authentication failures are written to the database.
After having changed the registry settings access requests to the protected web application folder will be matched against the database and IIS will use the mapped user account for all access.
Database settings
Two things must be added to the database in order for a user to be allowed access. First of all a user account must be created in the 'users' table:
- Login: The login name of the user
- Password: The password (in clear text) for the login account
- Enabled: Must be set to true (1)
- Expires: If set to false (0) the account does not expire
- Expiration: Determines the expiration time for the account. Only used if Expires is set to true (1)
- Administrator: Not currently used
In addition to the account itself site, directory permissions must be set for the user. This is done in the 'permissions' table:
- UserID: The ID of the user in the 'users' table
- SitePrefix: The IIS instance metapath for the site. For the first site on the system this is typically /LM/W3SVC/1
- PathPrefix: The URL path prefix for which the user should be granted access (e.g. /secret)
The PathPrefix can be used to allow access only to certain areas of the web site. To give access to the entire site the PathPrefix should be set to a single slash ('/').
Troubleshooting
Error in the ISAPI filter are most frequently related to the connection between the filter DLL and the database. Please make sure that the latest versions of relevant ODBC drivers are installed on your computer and check the database connection in the Data Sources (ODBC) applet in the Control Panel. Errors are logged to the system event log. Incorrect account information for the mapped account is not shown by the filter but might be logged by the web server or by the system itself.
Errors could also be the result of the account running the web server not having sufficient permission to update the relevant registry keys under HKLM\Software\Bergek\Authenticator.
Uninstallation
Remove the ISAPI filter from the IIS snap-in. Restart IIS and then remove the DLL, database ODBC DSN and the registry key HKLM \ Software \ Bergek \ Authenticator.
If you are unable to remove the DLL file, please make sure that the filter has been removed from within the IIS snapin and that the event viewer is not running.
