How to use the System.DirectoryServices namespace in ASP.NET (329986)
The information in this article applies to:
- Microsoft .NET Framework Class Libraries 1.1
- Microsoft .NET Framework Class Libraries 1.0 SP1
This article was previously published under Q329986 SUMMARYIntroduction 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 topMORE INFORMATIONWhat 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 topDouble-Hop IssueThe 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 "hop" 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 topHow to Acquire a Primary TokenIf 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 identity
impersonate="true"/ and authentication
mode="Windows", 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 identity
impersonate="false"/ and authentication
mode="Windows"
- When Machine.config is set to processModel
username=Domain\username,password=secret
- If identity
impersonate="false"/ 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 topError 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: "Failed: System.Runtime.InteropServices.COMException (0x80005000):
Unknown error (0x80005000) at
System.DirectoryServices.DirectoryEntry.Bind(Boolean throwIfFail)" "The
specified directory service attribute or value does not exist"
back
to the topTroubleshoot the Double-Hop IssueUse 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:
- Set the ASPX page security mechanism to use Basic only.
- 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- 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
- 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
"Failed to start monitoring
directory changes" error message when you browse to ASP.NET page
back
to the topADSI 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 topError That You May Receive When the ADSI Schema Cache Is Not
AvailableYou may receive errors. After you restart the server, the Web
application does not respond, and you may also receive the following error
message: 0x8000500C, "The property in cache cannot be
converted from native datatype" back
to the topTroubleshoot the ADSI Schema CacheIf 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 topREFERENCES264921 How IIS authenticates browser clients
232714 How to enable auditing of Directory Service access
283201 How to use delegation in Windows 2000 with COM+
317012 Process and request identity in ASP.NET
back
to the top
Modification Type: | Major | Last Reviewed: | 5/19/2005 |
---|
Keywords: | kbActiveDirectory kbDSWADSI2003Swept kbHOWTOmaster KB329986 kbAudDeveloper |
---|
|