Common System.DirectoryServices Issues and Solutions (READ ME FIRST).

Frequently Asked Questions:
---------------------------------------------

Q: My application works fine on my desktop, but blows up when I put it on the web. Why?
A: Your code runs with the same permissions as the process that executes it. When you run it on your desktop, it runs with YOUR credentials. When you run it on the web, it runs with ASPNET user or NETWORK SERVICE user (depending on platform). These accounts typically do not have access to AD, so access will be denied.

Q: How can I get my code running on the web then?
A: You have a variety of options, some better than others:
     1. Explicitly specify credentials on the DirectoryEntry - use the constructor or .Username and .Password (don't forget your AuthenticationTypes.Secure).
     2. Put your code into a COM+ component and run it with a domain user's identity
    3. Use delegation (<identity impersonate="true" />).
    4. Run the process (IIS process or ASPNET process) as a domain user. This means setting an App Pool identity in IIS6 or changing the Anonymous account in IIS5 and using impersonation.
    5. Programmatically impersonate a domain user when necessary.

Q: Which one should I choose?
A: It depends on what you want to accomplish. All have their uses and are appropriate in specific situations. Whether or not you are allowing Anonymous access will have a bearing on which one you should choose as well. Here are some common scenarios for when each one can be appropriate:

#1. If you are using Anonymous access or you want code to only be accessed with a single service account-like ID. If you are using IIS5 (XP or 2000 Server), this is not a terrible choice. The challenge becomes managing those credentials. You might need to store credentials in a config file or registry key and encrypt them using something like DPAPI. Once explicit credentials are specified, most problems go away (except for some SetPassword issues in Windows 2000). This is good typically for read-only type applications. Running with a more powerful account is generally not a good idea. If the account specified is a locked down service account, we don't have to worry about accidentally or maliciously updating the directory. If we really need to do something that updates the directory while using this technique, we should use #2, #3, or #5 in conjunction. I tend to prefer #4 before using this method at all, but sometimes it cannot be helped (e.g. using ADAM principals).

#2 This option relieves you of managing credentials by simply specifying them at deploy time in COM+ using the identity. The code will run with whatever permissions specified. You gain a small modicum off role based security here as well (if using Windows Authentication). The downside to this is that COM+ managed components are limited somewhat (no constructor, etc.), and can be a royal pain to deploy. Performance is not as good as other options, but typically good enough for most applications. This is good if you are doing a lot of Admin like functions where you want to let groups of users perform it without locking it to a user or giving them that permission specifically in the directory. It is perfectly acceptable to combine #1 and #5 or #4 and #5 instead of using this technique.

#3 Delegation is a powerful feature and allows us to access resources end to end with our own credentials. It is good when we really want people to be able to do (or not do) some function based on their inherent permissions. It is bad when we want groups of people to do things that they may not specifically have permission to do. For instance, this does not work well for helpdesk people who we typically don't want to give a bunch of permissions to, but we still want them to perform functions on our behalf. Using #4 and granting some of the helpdesk's necessary privileges to the service account is probably a better choice in that case.

#4 Running the process as a domain user is a lot like #1, but can be easier. In IIS6, this is simple using the App Pool (also add the service account to IIS_WPG group as well). In IIS5, this option is less appealing since we have to change the Anonymous account (IUSR_MACHINE) to a domain user and then impersonate using <identity impersonate="true"/>. For IIS6, we can combine the app pool identity with Windows Authentication, but for IIS5, this is only appropriate for running an Anonymous site (maybe using Forms Auth). This is good for read-only access and some limited rights (like unlock account), but again, not a good idea if we need to update the directory as well. It can be combined with #5 for update access for more privileged tasks. Do not run websites with powerful service accounts.

#5 This option is typically used when we need to perform an Administrative function. We can temporarily impersonate an admin to perform the action and then revert back to a less powerful account. This is good for combining with #1 or #4. Similar to #1, the hurdle is to manage the credentials. It is strongly encouraged not store these credentials in plaintext. They should be encrypted using DPAPI and stored in either the registry (further ACL'd for more security), or a config file. Depending on the task, you might be able to use #4 with a read-only service account for most tasks and then use #1 (carefully managing credentials) for the more privileged tasks.

Q: How do I get Kerberos delegation working?
A: Here are two methods to get this working for IIS applications. The only addition to this is that if you are using Window 2003, you should also combine this with constrained delegation to make sure that other resources are not being accessed.

When running with local service account (NETWORK SERVICE) App Pool

Server-side tasks:
---------------------------------------------------------------------------------
1. IIS server must be a member of the domain and <identity impersonate="true"/> should be in web.config
2. Set IIS server computer account in AD Users & Computers MMC as "Trusted for Delegation"
3. IIS Server must be rebooted for this policy to take effect.
4. Integrated Windows Authentication only must be selected for site / virtual directory
5. IIS must not have NTLM only set as authentication method (this is usually not a problem, NEGOTIATE is default, so unless you specifically ran a script to change this, don't worry about it).
6. IIS server name either must match exactly account name in AD, or SetSPN tool should be used in cases where IIS site is set as alternative name (e.g. server is called server01.domain.com, and website is called www.application.com).

When running with Domain Service Account App Pool (i.e. #4 above)

Server-side tasks:
---------------------------------------------------------------------------------
1. IIS server must be a member of the domain and <identity impersonate="true"/> should be in web.config
2. Set Domain's App Pool Identity account in AD Users & Computers MMC as "Trusted for Delegation"
3. SetSPN must be used to add SPN to domain service account (e.g. "HTTP/www.myapplication.com").
4. Integrated Windows Authentication only must be selected for site / virtual directory
5. IIS must not have NTLM only set as authentication method (this is usually not a problem, NEGOTIATE is default, so unless you specifically ran a script to change this, don't worry about it).

Client-side tasks
---------------------------------------------------------------------------------
1. Client must be using IE 5.x+. If client is running IE 6, ensure that "Enable Integrated Windows Authentication (requires restart)" is selected from Tools > Internet Options > Advanced.
2. Web site MUST be recognized as Local Intranet (not Internet Zone) site to client. I have not seen any documentation explaining why, but I just have never been able to get it to work otherwise. If necessary, specifically add this to Local Intranet sites list.
3. Client account must not be marked as "Sensitive, Do not Delegate" in AD Users and Computers MMC.

Q: How do I programmatically impersonate an Admin?
A: There are some challenges with this. If you are running Windows 2000, we typically need to use LogonUser api to get a token which requires giving the TCB priviledge (Act as part of the operating system). That, or we need to run ASPNET as SYSTEM account. Either way, the system is at risk here and can be owned. Windows 2003 and XP do not have this limitation. Keith Brown (www.pluralsight.com) has a sample on how to get a user's token from outside the TCB, which sidesteps this issue for Windows 2000 servers.

There are sample components you can use for impersonation, here is one:

http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=A2DC32A8-4313-4B14-9EE9-8234A8395821

Q: I am getting errors when I run this stuff, what is the problem?
A: Have you given enough information to troubleshoot this? Which method (from above) are you using for access? Is there more than 1 domain involved or trusts? I have found that 90% of the issues with System.DirectoryServices code are related to security and your binding context. If you don't understand your context you are pretty screwed to begin with. Understand what security context your code is executing under!

Q: I need to change a password, how do I do this?
A: If you want the user to change their own password - use 'ChangePassword'. If you want an Administrator to reset a password on someone's behalf, you need to use 'SetPassword'. Installing an SSL cert on your DC will solve almost all password change related problems. Without it, Kerberos or an underlying api call must be made. Sometimes the security context does not transfer and you get issues. Method #5 from above can help here (especially for Windows 2000).

There is a good conversation on how to use SetPassword (and sample code) on this forum here:

http://forums.asp.net/316534/ShowPost.aspx