HOWTO: Launching OLE Servers from ISAPI Extensions

• Microsoft OLE libraries included with:

      - Microsoft Windows NT 4.0
  

SUMMARY

An OLE server that is an EXE must include the IUSR_computername Internet guest account in its launch and access security permissions before it can be launched by an ISAPI extension DLL. In addition, if the server is an EXE server that is not a Win32 service, it must be configured to run under a specific user account using the RunAs registry value.

MORE INFORMATION

Adding Launch and Access Permissions

In NT 4.0, EXE OLE servers use activation security to specify the security contexts of clients that can activate the server. The server specifies this by using the HKEY_CLASSES_ROOT\AppID\{...}\LaunchPermission & AccessPermission keys or by defaulting to the default activation security for all servers on a machine specified by the HKEY_LOCAL_MACHINE\Software\Microsoft\OLE\DefaultLaunchPermission and DefaultAccessPermission keys. The values of these keys can be set using the DCOMCNFG.EXE graphical utility included in NT 4.0. Activation security is automatically applied by the Service Control Manager of a particular machine. Upon receipt of a request to activate an object from a client running in a different security context, the Service Control Manager checks the request against the Access Control List (ACL) specified by the above keys and will fail the activation if the client's security identifier is not in the ACL.

The Internet Information Service (IIS) runs in the LocalSystem account. However, the IIS thread that executes an ISAPI extension DLL impersonates the IUSR_computername account, which is an Internet guest account created when IIS is installed. The default launch and access permissions of OLE servers do not give IUSR_computername permission to launch the server. As a consequence, a CoCreateInstance call from an ISAPI extension DLL will fail with E_ACCESSDENIED.

This problem can be solved by adding the IUSR_computername to the OLE server's launch and access permissions using the DCOMCNFG.EXE utility.

IUSR_computername need not be added to the launch and access permissions of inproc OLE servers. For inproc OLE servers, make sure that SYSTEM is listed in the DefaultAccessPermissions, and CoCreateInstance will succeed.

For example, use the following steps to add to the Default Launch and Activation permissions:

1. Launch DCOMCNFG.EXE, which can be found in the system32 directory of the Windows NT 4.0 installation.

2. Click the Default Security tab.

3. Click the Edit Default button in the Default Launch Permissions group.

4. Click the Add button in the Registry Value Permissions dialog.

5. Click the computer name from the “List Names From” combo box.

6. Click the Show Users button.

7. Select and add the IUSR_computername Internet Guest Account. For example, add IUSR_FOO, where FOO is the machine name. Click OK to get out of the dialogs, and then click Apply.

8. Similarly, add IUSR_computername to the Default Access Permissions.

Preventing USER32 Window Station/Desktop Failure

When IIS calls OleInitialize, OLE will cache the window station and desktop that are connected to the IIS process in the LocalSystem account. The IIS thread that executes the ISAPI extension DLL impersonates the IUSR_computername account. When the extension DLL calls CoCreateInstance to create an EXE server (which is not a service and is not marked with RunAs in the registry), OLE will call CreateProcess to create the server and will pass the cached window station and desktop in the STARTUPINFO parameter. The server will be run in the client's security context (IUSR_computername) because it is not a service and not marked with RunAs. The launched server will cause the following USER32 error:

   "Initialization of the dynamic linked library USER32.DLL failed. The
   process is terminating abnormally".

This problem can be solved by configuring the server using the RunAs registry value to run under a user account. This can be “Interactive User” if an interactive user will be logged on, or can be a specific user account if an interactive user will not be logged on. If “Interactive User” is specified, the server will run in the interactive user's account and will connect to the interactive desktop. If a specific user account is specified, the server will run in that account and connect to its own window station and desktop. As a consequence, the USER32 error will not occur.

For example, use the following steps to configure a server to run under a user account:

1. Run DCOMCNFG.EXE.

2. Click the Applications tab, and then click the server.

3. Click the Properties button, and then click the Identity tab.

4. Select “The interactive user” if an interactive user will be logged on when the server is launched, or select “This user” and specify a user if an interactive user will not be logged on when the server is launched. This will add a RunAs registry entry under the APPID key of the server.

5. Make sure that the specified user is given launch and access permissions to the server.

Another solution to this USER32 problem is to call RevertToSelf before calling CoCreateInstance in the ISAPI extension. The thread will revert from the IUSR_computername account to the LocalSystem account and the launched server will run in the LocalSystem account. The USER32 error will not occur because the server will be able to connect to the window station and desktop of the IIS process, which also runs in the LocalSystem account. However, running a server in LocalSystem has a couple of problems:

1. LocalSystem is a highly-privileged account, and running a server in it may give it more privileges than may be acceptable to you.

2. The server will not be able to call to another machine using any secure communications mechanism, including DCOM, because LocalSystem does not have network rights. Consequently, the first solution is recommended.