ISAPI extensions can be divided into two broad categories, pending and nonpending. 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 nonpending case is illustrated in the following diagram.
When IIS processes a request, it verifies that the client has permission to access any requested resources. IIS supports four different authentication schemes for performing this check: anonymous, Basic, integrated Windows 2000 (NTLM) authentication, 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, by default, to IUSR_machinename. If either Basic or integrated Windows 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 ImpersonateLoggedOnUser on the current Input/Output thread so that the thread is running as the authenticated user. Because the nonpending ISAPI extension 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. 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 structure. If the call to the ServerSupportFunction was for a synchronous operation, the EXTENSION_CONTROL_BLOCK is valid until the HttpExtensionProc function completes. If the call to the ServerSupportFunction was for an asynchronous operation, the EXTENSION_CONTROL_BLOCK 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. 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. 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, by default, IWAM_machinename.