Microsoft KB Archive/329986

= How to use the System.DirectoryServices namespace in ASP.NET =

Article ID: 329986

Article Last Modified on 5/19/2005

-

APPLIES TO


 * Microsoft .NET Framework Class Libraries 1.1
 * Microsoft .NET Framework 1.0 Service Pack 1

-



This article was previously published under Q329986



Table of Contents

 * Introduction
 * What is a Primary Token?
 * What is the Double-Hop Issue?
 * How to Acquire a Primary Token
 * Error That You May Receive If You Do Not Have a Primary Token
 * Troubleshoot the Primary Token and Double-Hop Issue
 * ASP.NET Base Account
 * Error That You May Receive If the ASP.NET Base Account is Not Set Correctly
 * Troubleshoot ASP.NET Base Account
 * ADSI Schema Cache
 * Error That You May Receive When the ADSI Schema Cache Is Not Available
 * Troubleshoot ADSI Schema Cache
 * REFERENCES



Introduction
This article addresses problems that occur when an application that is written in Visual Studio .NET by using the System.DirectoryServices namespace works properly from a Windows-based or command line application but does not succeed in ASP.NET. If you experience this symptom, the problem pertains to security. The System.DirectoryServices namespace uses Active Directory Services Interfaces (ADSI) to contact discrete directory services by means of the different ADSI providers.

This article assumes that you, the application designer, want the directory to be contacted under the security context of the ASP.NET Web user. If you do not want to do that, or you do not want to perform the resolutions that are listed in this article, you can work around these problems by passing credentials to your DirectoryServices code through the class constructor, or by using the Username and Password properties.

back to the top



What is a Primary Token?
The Active Directory (AD) relies on the security mechanism of the Windows 2000 server. To access most information in the AD, you must provide credentials to the Windows 2000 server when requesting the AD information. The credentials you provide must be in a primary token, which just means that the IIS server has a password (not just a hash of the password) to pass to the AD.

back to the top

Double-Hop Issue
The double-hop issue is when the ASPX page tries to use resources that are located on a server that is different from the IIS server. In our case, the first &quot;hop&quot; is from the web browser client to the IIS ASPX page; the second hop is to the AD. The AD requires a primary token. Therefore, the IIS server must know the password for the client to pass a primary token to the AD. If the IIS server has a secondary token, the NTAUTHORITY\ANONYMOUS account credentials are used. This account is not a domain account and has very limited access to the AD.

The double-hop using a secondary token occurs, for example, when the browser client is authenticated to the IIS ASPX page by using NTLM authentication. In this example, the IIS server has a hashed version of the password as a result of using NTLM. If IIS turns around and passes the credentials to the AD, IIS is passing a hashed password. The AD cannot verify the password and, instead, authenticates by using the NTAUTHORITY\ANONYMOUS LOGON.

On the other hand, if your browser client is authenticated to the IIS ASPX page by using Basic authentication, the IIS server has the client password and can make a primary token to pass to the AD. The AD can verify the password and does authenticate as the domain user.

For more information, click the following article number to view the article in the Microsoft Knowledge Base:

264921 How IIS authenticates browser clients

back to the top

How to Acquire a Primary Token
If the IIS server has a primary token to pass on, the IIS server can pass a primary token to the AD on behalf of the client requesting the ASPX page. To acquire a primary token by using ASPX, use one of the following methods.

Method A
When the Web.config file is set to  and , use the Anonymous account with the following settings:
 * On the ASPX page, set the security mechanism to Anonymous only.
 * Clear the Allow IIS to control the password check box.
 * Set the Anonymous account to be a domain user.

Method B
When Web.config and Machine.config are set as follows:
 * When Web.config is set to  and
 * When Machine.config is set to
 * If  in the Web.config file, the credentials of the Base process are used. When you supply a domain user and password, you make it possible for IIS to pass a primary token to the AD.

back to the top

Error That You May Receive If You Do Not Have a Primary Token
If the code works when you browse to it from the development machine that is a Web server, but the code does not work when other Web clients access the pages, you may receive an error message that is similar to one of the following:

&quot;Failed: System.Runtime.InteropServices.COMException (0x80005000): Unknown error (0x80005000) at System.DirectoryServices.DirectoryEntry.Bind(Boolean throwIfFail)&quot;

&quot;The specified directory service attribute or value does not exist&quot;

back to the top

Troubleshoot the Double-Hop Issue
Use one of the following methods to troubleshoot the double-hop issue.

Quick Test
To quickly determine whether this is a permissions issue, follow these steps:
 * 1) Set the ASPX page security mechanism to use Basic only.
 * 2) Use a client to browse to the ASPX page, and then provide domain credentials when prompted.

If this works, you can conclude that the double-hop issue is probably the problem.

Test Your Code
Another good troubleshooting test for any IIS ASPX issue when you access the AD involves taking your ASPX code out of the IIS environment and running it as a script file on the IIS server itself. Follow these steps:  Log on to the IIS server as the domain account that your browser was trying to use, and then run the code.

This test removes the IIS server from the environment and helps you narrow down the problem. To determine whether this is a double-hop issue, turn on auditing for directory service objects. For more information about how to do this for the Active Directory, click the following article number to view the article in the Microsoft Knowledge Base:

232714 How to enable auditing of Directory Service access

After you turn on logging, events are written to the security event log.

If this is your issue, you can find events in the security event log that are similar to the following:

Event Type: Success Audit Event Source: Security Event Category: Directory Service Access Event ID: 565 Date: 3/27/2002 Time: 3:21:41 PM User:  NT AUTHORITY\ANONYMOUS LOGON Computer: TESTDC Description: Object Open: Object Server: DS Object Type: user Object Name: CN=Users,DC=corp,DC=com New Handle ID: 0 Operation ID: {0,68019232} Process ID: 264 Primary User Name: TESTDC$ Primary Domain: TESTDOM Primary Logon ID: (0x0,0x3E7) Client User Name: ANONYMOUS LOGON Client Domain: NT AUTHORITY Client Logon ID: (0x0,0x40DE417) Accesses READ_CONTROL Privileges - Properties:

Note: The directory service has been contacted as the anonymous user. This is because the credentials of the Web user cannot be correctly conveyed to the directory service. For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base:

264921 How IIS authenticates browser clients

283201 How to use delegation in Windows 2000 with COM+

For more information, click the following article number to view the article in the Microsoft Knowledge Base:

317012 Process and request identity in ASP.NET

back to the top



ASP.NET Base Account
By default, all ASP.NET applications run under the base process account, MACHINENAME\ASPNET. This is a local account that does not have access to objects in Active Directory. To access Active Directory by using the credentials that are passed to IIS, you must modify your Web.config file to contain the parameters identity impersonate=&quot;true&quot; and authentication mode=&quot;Windows&quot;. The presence of these two parameters causes ASP.NET to run the code under the credentials that are passed to it by IIS.

Note This is very similar to how classic ASP currently works. A High-Isolated or Out-of-Process (OOP) application is actually running in a separate DllHost process. DllHost's base process is IWAM_machinename. When calls are made to this OOP, it impersonates the user who was authenticated by IIS. With ASP.NET, pages will run in a separate process also, that process being Aspnet_wp.exe. By using the  tag, the application designer controls whether that impersonation is performed. For more information, click the following article number to view the article in the Microsoft Knowledge Base:

317012 Process and request identity in ASP.NET

back to the top

Error That You May Receive If the ASP.NET Base Account Is Not Set Correctly
If the ASP.NET Base account is not set correctly, you may receive one of the following error messages:

Cannot contact the specified domain or domain does not exist

Logon Failure: Unknown Username or bad password

back to the top

Troubleshoot ASP.NET Base Account Not Set Correctly
 If you have modified your Web.config file to use impersonation, but your DirectoryServices code does not succeed and you receive the same errors (see errors mentioned earlier in this article), the problem is probably caused by a default behavior in IIS. By default, the new virtual directory setup in IIS has Anonymous Authentication turned on. To resolve this, open Internet Services Manager and modify the authentication methods of the virtual directory to clear the Anonymous Authentication check box. Although you call DirectoryEntry.Invoke for SetPassword (or for another method that is exposed) on the underlying ADSI interfaces, and you receive the following error message, the error number that is returned is not 0x8000500D:

The Active Directory property cannot be found in the cache

The expected behavior is that error number 0x8000500D is returned with this description.

For example:

COMException (0x80020006): The Active Directory property cannot be found in the cache

The confusion is that the cause of this error, as indicated by the error number, may not correspond to the error description. The cause of this error should be identified by the error number, and not by the description. Generally, you can expect the resolution to your problem to be determined by the error number, not by the description. In this example, the error number corresponds to DISP_E_UNKNOWNNAME.</li></ul>

<div class="moreinformation_section">

<ul> If your IIS server is running on a Domain Control or Backup Domain Controller, the default base account may not work and you may receive errors. For more information and the descriptions of these error messages, click the following article number to view the article in the Microsoft Knowledge Base:

315158 FIX: ASP.NET does not work with the default ASP.NET account on a domain controller

</li> If your base IIS server does not have rights to read, execute, and list on the root Web site, you receive an error when you browse to a Web page. For more information, click the following article number to view the article in the Microsoft Knowledge Base:

316721 &quot;Failed to start monitoring directory changes&quot; error message when you browse to ASP.NET page

</li></ul>

back to the top

ADSI Schema Cache
ADSI tries to cache the schema from the AD. The schema cache is used to determine how to read the attributes out of the attribute cache. If ADSI cannot cache the schema, it uses a V2 version of the schema. The V2 version of the schema contains a very small set of attributes. For more information, click the following article number to view the article in the Microsoft Knowledge Base:

251189 After locating an LDAP server schema cached by ADSI

ADSI will try to cache the schema only one time per process. In Windows 2000, ASP.NET runs under a single aspnet_wp.exe process. This means that the schema will not be cached again until the IIS service is shut down and restarted.

Subsequent Schema cache access may depend on the user rights of the first user who runs an ASP.NET page that uses ADSI on that server.

In a typical scenario, an administrator notices that the application works by launching a Web browser locally. The Web site is then made live and works for a period of time until the server is rebooted or Web services are restarted.

At this point, the ASP.NET application stops working, because ADSI did not cache the schema correctly. This may happen when the first user to access the Web site cannot establish the credentials to correctly cache the schema. This is a likely scenario when a user suffers from the double-hop problem described earlier in this article. You may not quickly realize that this has happened because you may not see either of the following error messages:

Permission Denied

Property not Found in Cache

This may be due to the method that was used to install the Active Directory. When the first domain controller in the domain is promoted, the DCPromo Wizard asks whether the Domain should be compatible with Windows NT 4 or with only Windows 2000. If you accept the default of Compatible permissions with NT4, the security principal EVERYONE is added to the Pre-Windows 2000 Compatible Access built-in group. This is significant because, by default, the Pre-Windows 2000 Compatible Access group has List Contents and Read All Properties permissions on many objects in the directory. Because the Anonymous user will access the directory service as EVERYONE, that anonymous user will get many attributes returned in a query and loaded into the attribute cache.

The schema that ADSI uses is stored in the cn=Aggregate object in the schema namespace. Neither the Pre-Windows 2000 Compatible Access built-in group nor the Everyone principal have permissions on this aggregate object. Therefore, schema information is not accessible. The result is that there is a property in the attribute cache that was retrieved from the server that ADSI does not understand. Because ADSI cannot determine the data type, you receive the error that is mentioned in the next paragraph.

back to the top

Error That You May Receive When the ADSI Schema Cache Is Not Available
You may receive errors. After you restart the server, the Web application does not respond, and you may also receive the following error message:

0x8000500C, &quot;The property in cache cannot be converted from native datatype&quot;

back to the top

Troubleshoot the ADSI Schema Cache
If you receive the error that is mentioned in the previous paragraph, ADSI is not correctly caching your Active Directory schema. For more information and to verify whether the registry key was made and whether the file was written as described in another article, click the following article number to view the article in the Microsoft Knowledge Base:

251189 Locating an LDAP server schema cached by ADSI

Registry Keys and Resolving the Issue

 * If the registry keys are present, delete them, stop and restart IIS, and then browse to the Web page.
 * If the key is not created or the file is not written, either you do not have the permissions to download the schema cache from the server, or you do not have the permissions to write the file or create the registry key. If they are written, you can expect the page to work until the next time that IIS restarts.

To resolve this, you must resolve the double-hop issue.

back to the top

<div class="references_section">