Pubcookie Home > Documentation 
 
Pubcookie Homepage Pubcookie ISAPI Filter
Windows Registry Settings
Component:  Pubcookie ISAPI Filter
Audience:  All
Modified:  September 17, 2004

The Pubcookie ISAPI Filter for Microsoft IIS is configured by properties set in the Windows registry. Pubcookie's registry settings are divided into two categories: web properties and filter variables. Web properties are used to configure webs, applications, folders, and files. Filter variables configure the filter itself.

Included on this page:

PubcookeFilter Registry Key

All of Pubookie's registry settings are found under the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PubcookieFilter

Use Example

When used to change the Windows registry this example.reg.txt file sets four filter variables and four web properties specific to one application, called WebApp. Notice that the AuthTypeName1 setting defines the string used by the AuthType setting.

Web Properties

In Pubcookie terms, a web property is used to configure any web, subfolder, or file. Think of them as per-application or per-resource settings. They take effect immediately upon entry into the registry without the need to reset the Pubcookie filter.

Property Name Data Type Description Default Value
AppID String Application ID. A case-insensitive string. first node in the path from wwwroot
AuthType String Authentication type, as offered by your login server. The string is case-insensitive. Default values are "UWNetID", "SecurID", or "None". These strings can be redefined using filter variables. AuthTypeName0 (i.e. "None")
Default_Url String Partial URL path to return to after Hard/Inactive timeout login ""
Enterprise_Domain String Domain for scoping granting request cookie .washington.edu
Error_Page String Partial URL path for authentication errors ""
Hard_Timeout DWORD Session cookie times out after this value in seconds ( 8 * 60 * 60 )
Inactive_Timeout DWORD Session cookie times out after this value in seconds without session activity ( 30 * 60 )
Logout_Action DWORD Value Action 0
0 No logout action
1 Clear session cookie and serve page; implicitly sets AuthType to None to serve page
2 Clear session cookie and redirect to login server
3 Clear session cookie, redirect to to login server, and clear login cookie
NtUserId String Id of Windows account to run this app as (e.g. YOUR_DOMAIN\\SOME_ACCOUNT). NTUserId is not required. Use it in special situations where your IUSR_HOSTNAME account does not work (e.g., for connecting to your SQL Server). If used, it is best to create a special account, making sure it has "log on locally" user rights. In version 2.7 and higher, only honored in legacy dirs. ""
Password String Cleartext password for NtUserID. In version 2.7 and higher, only honored in legacy dirs. ""
Session_Reauth DWORD Require re-authentication for this resource even with valid login cookie. 0 (false) or 1 (true) 0
Timeout_Url String Partial URL path to send user to if Hard/Inactive timeout. It should not be in a protected folder ""
Web_Login String URL of Pubcookie login server ""

To assign a web property to a resource, set the corresponding PubcookieFilter registry key. For example:

HKLM\SYSTEM\CurrentControlSet\Services\PubcookieFilter\<APPID>\<SUBDIR>\...\<FILE>

The APPID is required, but the subdirectory and filename are optional. The subdirectory structure should mirror that of the virtual directory structure of the filtered web.

A special key, HKLM\SYSTEM\CurrentControlSet\Services\PubcookieFilter\Default, will override the default web property values shown in the table above. This means that "Default" is a reserved word; it cannot be used as an application name.

All web properties are inherited from higher-level subdirectories and overridden by lower-level subdirectories and file entries. For example, if AuthType is set to UWNetID in the application MYAPP, set to SecurID in MYAPP\SubDir, and set to None in MYAPP\SubDir\myfile.html, then MYAPP\SubDir\myfile.html will have the AuthType of None, but another unspecified file in MYAPP\SubDir will have the AuthType of SecurID.

To support legacy webs (i.e. Pubcookie filter 2.6 and below), the special subdirecotry names "UWNETID", "None", and "SecurID" will set the AuthType property to "UWNetID", "None", and "SecurID", respectively. These three strings can be redefined using filter variables (see below). Support for legacy webs can be turned off by setting the filter variable LegacyDirNames to 0.

Filter Variables

In Pubookie terms, a filter variable is used to control the default behavior of the Pubcookie ISAPI Filter itself. These settings are defined in the registry under the following key:

HKLM\SYSTEM\CurrentControlSet\Services\PubcookieFilter

They all require a filter reset to be re-read. (They can also be defined at compile time in pbc_config.h.)

Variable Name Data Type Description Default Value
Debug_Dir String Directory in which to place debug log. Relative to SystemRoot "\LogFiles\PubcookieFilter"
Debug_Trace DWORD Control debugging. 0=off, 1=on 0
DEFAULT_APP_name String Name to assign if application name cannot be determined, e.g. request to / "defaultapp"
Ignore_Poll DWORD Set to "1" to ignore Network Dispatcher "/" polls 0
LegacyDirNames DWORD Support for legacy directory names to set AuthType. 1=True, 0=False 1
Login_URI String Login server URI ""
Keymgt_URI String Keyserver URI  
AuthTypeName0 String Name of authentication type that corresponds to no authentication "None"
AuthTypeName1 String Name of authentication type that corresponds with authentication by the basic login flavor (flavor_basic) in a 3.0 login server. "UWNetID"
AuthTypeName2 String Name of authentication type -- at the University of Washington -- that corresponds with the SecurID login flavor. Other sites may not a second flavor. "SecurID"
Public_dir_name String Name of legacy directory that will set AuthType to no authentication "Public"
NetID_dir_name String Name of legacy directory that will set AuthType to regular pubcookie authentication "UWNetID"
SecurID_dir_name String Name of legacy directory that will set AuthType to pubcookie plus SecureID authentication "SecurID"
System_Root String Base directory for Pubcookie debug and config files. Leave blank to use Windows' system dir ""

Pubcookie 3.0 Filter Reset

With Pubcookie 3.0, you can force the Pubcookie filter to re-read the Windows registry for new filter variables by doing an iisreset or by opening a special Pubcookie reset URL on your application server. For example:

http://appserver.example.edu/pubcookiefilter_reset

Note: Just stopping and starting the Web won't bounce the PubcookieFilter DLL.

Note: Pubcookie 3.1 doesn't require this step. It will read new settings on every request.


[Pubcookie Home Page]
Copyright © 2002-2008 University of Washington
UW Technology Services
Pubcookie Contact Info
Modified: September 17, 2004