Security for ISAPI extensions is derived from the Microsoft® Windows NT® security model. If your extension accesses secured system resources, it must obtain the appropriate Windows NT permissions. Several inter-related issues determine how you accomplish this programming task. This topic provides an overview of these security issues and outlines the processing steps required to access secured resources.
The topic is divided into the following sub-sections:
Every Microsoft® Windows NT® process has a unique process identity which is used by the Windows NT object manager for various management tasks. Each process object contains an associated access token, which indicates the type of access rights the process has for secured resources. ISAPI extensions either run in the inetinfo process or in an isolated process. The process identity for applications running in the intetinfo process is SYSTEM. The process identity for isolated applications is IWAM_<machinename>.
A very simple ISAPI extension will be able to respond to the request and immediately return the required information. More complex extensions, however, will rely on worker threads to accomplish their processing. By default, worker threads have the same identity as the process in which they are running. If your ISAPI accesses secured resources, it will need to pass the security context of the logged-on user to a thread. The security context is passed to the thread by obtaining an impersonation token from the process. The detailed steps for obtaining an impersonation token are described in the Process Execution section.
ISAPI extensions can be divided into two broad categories, pending and non-pending. A pending extension returns the value HSE_STATUS_PENDING from the initial call to HttpExtensionProc. The process of obtaining a security token for a thread is slightly different for these two categories. The process for the non-pending case is illustrated in the following diagram.
When IIS processes a request, it verifies that the client has permission to access any requested resources.(Step 1) IIS supports four different authentication schemes for performing this check: anonymous, basic, Windows NT Challenge/Response, and Client Certificates. Regardless of which authentication scheme is used, once the client has been authenticated, the request has an established security context. If the authentication scheme used is anonymous, the security context will be set to IUSR_machinename. If either Basic or NTLM authentication has been used, the security context will be set to the account the user logged in with on the client machine.
After IIS has authenticated the user, it calls SetThreadToken on the current Input/Output thread so that the thread is running as the authenticated user. (Step 2). Because the non-pending ISAPI extensions is called with the security context of the authenticated user, it can access the same secured resources as the authenticated user.
In the case of the pending extension, the process of setting the appropriate security context requires some additional steps. This is illustrated in the following diagram.
Because the pending ISAPI extension needs to access the current security context it calls ServerSupportFunction and specifies HSE_REQ_GET_IMPERSONATION_TOKEN as the value for the dwHSERequest parameter. (Step 3) This function returns a handle that you can use to obtain an impersonation token for a worker thread.
Note The handle for the impersonation token that is returned will be valid for the lifetime of the EXTENSION_CONTROL_BLOCK (ECB). If the call to the ServerSupportFunction was for a synchronous operation, the ECB is valid until the HttpExtensionProc function completes. If the call to the ServerSupportFunction was for an asynchronous operation, the ECB will be valid until your extension calls ServerSupportFunction and specifies a value of HSE_REQ_DONE_WITH_SESSION for the dwHSERequest parameter.
When the thread needs to access secured system resources, it should call either ImpersonateLoggedonUser or SetThreadToken and pass the reference to the handle it received from the ServerSupportFunction as an input parameter. (Step 4) Both ImpersonateLoggedonUser or SetThreadToken are Win32 API functions.
You may want to call the Win32 API RevertToSelf function after the thread has finished using the current security context (Step 5). Calling RevertToSelf will return the thread to the security context of the process in which it is running. For ISAPI extensions running in the INETINFO process, the security context is SYSTEM. For ISAPI extensions running in an isolated process, the security context is IWAM_machinename.
For more information on IIS authentication see Authentication in the Server Administration section.
For more information on the Win32 API's, see the Platform SDK.