Accessing Active Directory Through the .NET Framework

Our user object has two default constructors. The first is used to initialize our user with a given DirectoryEntry object. It will attempt to use the Invoke method to "Get" the user's properties off of the object.

The second constructor is used to create a new user. You only need to pass in the three required parameters and it will create a new DSUser object for you to use when creating a new user. Notice that no AD work is being done, thus no real user in your AD is being created yet.

The DAL

The next step is to create the DAL wrapper for AD. The next few sections of code will be a break down of the entire UserAdmin DAL. For a complete listing please see the downloadable.

We first create and initialize the variables we will need in our UserAdmin class:

 
    #region default property initialization
    //our error logging device.  keeping it simple to avoid bloating sample code
    System.Text.StringBuilder errorLog = new System.Text.StringBuilder();
    private System.Boolean error=false;
    public System.Boolean Error{get{return error;}}
    public string ErrorLog{get{return errorLog.ToString();}}

    //setup default properties
    private string loginPath="WinNT://"+Environment.MachineName+",computer";
    private string domainName=null;
    private string loginUsername=null;
    private string loginPassword=null;
    private System.DirectoryServices.AuthenticationTypes authenticationType = System.DirectoryServices.AuthenticationTypes.None;
    private System.DirectoryServices.DirectoryEntry AD=null;
    private System.Boolean connected=false;
    #endregion

Notice how we hardcode the LoginPath to be the WinNT provider. This would need to be changed in order for this DAL to work with any of the other AD service providers. Also notice that I simplified error handling by using a System.Text.StringBuilder object to hold the error log. In the case of an error, it will simply be appended to this, and the "error" Boolean variable will be set.

The next region of code to examine is the constructors for our class (see Figure 1.4, below).

    #region .ctor's
    public UserAdmin() {
      Connect();
    }

    /// <summary>
    /// Allows you to create a UserAdmin class specifying all credentials, if needed
    /// </summary>
    /// <param name="LoginUsername"></param>
    /// <param name="LoginPassword"></param>

    /// <param name="AuthenticationType"></param>
    /// <param name="DomainName"></param>
    public UserAdmin(string LoginUsername, string LoginPassword,
		System.DirectoryServices.AuthenticationTypes AuthenticationType, string DomainName) {
      loginUsername=LoginUsername;
      loginPassword=LoginPassword;
      authenticationType=AuthenticationType;
      if(DomainName=="" || DomainName==null) DomainName=System.Environment.UserDomainName;
      domainName=DomainName;
      Connect();
    }

    /// <summary>
    /// An alternative way to get a UserAdmin class which allows you to specify an alternative LoginPath, for example LDAP, or IIS
    /// </summary>

    /// <param name="LoginPath"></param>
    /// <param name="LoginUsername"></param>
    /// <param name="LoginPassword"></param>
    /// <param name="AuthenticationType"></param>

    /// <param name="DomainName"></param>
    public UserAdmin(string LoginPath, string LoginUsername, string LoginPassword,
		System.DirectoryServices.AuthenticationTypes AuthenticationType, string DomainName) {
      loginPath=LoginPath;
      loginUsername=LoginUsername;
      loginPassword=LoginPassword;
      authenticationType=AuthenticationType;
      if(DomainName=="" || DomainName==null) DomainName=System.Environment.UserDomainName;
      domainName=DomainName;
      Connect();
    }
    #endregion

The first constructor provided is the basic default constructor. This allows our object to be created without any given parameters. Since there are no required pieces of data needed, we allow for this. This means that the object will connect to the local WinNT provider with no special security privileges.

The second constructor provided allows us to specify the login credentials for connecting to the AD for the given domain. This is handy when you want to connect to the any domain with the given credentials.

Finally, the last constructor adds the LoginPath parameter. This allows you to override the LoginPath, which gives you the ability to choose an alternative service provider than the default.

The next region of code is what I call the "Action Methods." There is actually quite an abundance of code so please refer to the downloadable source file while covering these methods. The methods in order are as follows:

public DSHelper.DSUser LoadUser(string username)

public System.Boolean AddUserToGroup(string groupname, DSHelper.DSUser dsUser) 

public System.Collections.ArrayList GetGroups()

public System.Boolean DeleteUser(DSHelper.DSUser dsUser)

public System.DirectoryServices.DirectoryEntry SaveUser(DSHelper.DSUser dsUser)

public System.Boolean Connect()

With that high-level overview, let's put it all together and see just how we would use this DAL to create an ASP.NET user administration page.

ASP.NET User Admin Page

This sample project gives you the ability to enter in the username and password for the administrator user (to actual make changes you will need to supply these credentials). It also offers a a text box so you can enter in the name of any user account for the domain, and it will list its properties. You can edit and save, or delete that user entirely.

Take time now to review the project in detail. Concentrate on the portions where we interact with the DAL. Think of new ways to improve the interface, and actually create a more useable and friendly design. Also consider how you could create an interface using a console application.

Impersonation

The word "Impersonation" indicates that we can act as another person or user. Within our ASP.NET applications this means we can temporarily act as another user, instead of the ASP.NET user that is the default account that IIS uses for anonymous access. We want to be able to allow our code to impersonate another user that has greater access to the AD resource that we need to modify. This is accomplished fairly easily.

    #region setup impersonation via interop
    //need to import from COM via InteropServices to do the impersonation when saving the details
    public const int LOGON32_LOGON_INTERACTIVE = 2;
    public const int LOGON32_PROVIDER_DEFAULT = 0;
    System.Security.Principal.WindowsImpersonationContext impersonationContext; 

[DllImport("advapi32.dll", CharSet=CharSet.Auto)]public static extern int LogonUser(String lpszUserName,
String lpszDomain,String lpszPassword,int dwLogonType,int dwLogonProvider,ref IntPtr phToken);
    
[DllImport("advapi32.dll", CharSet=System.Runtime.InteropServices.CharSet.Auto, SetLastError=true)]public
extern static int DuplicateToken(IntPtr hToken, int impersonationLevel,  ref IntPtr hNewToken);
    #endregion

First we need to import a few methods from the advapi32.dll, including a couple of helpful constants. The variable named impersonationContext will be used to hold the Windows user prior to the impersonation operation.

Now that we have set up impersonation, here is an example of how to use it:

if(impersonateValidUser(this.LoginUsername, this.DomainName, this.loginPassword)) {
  //Insert your code that runs under the security context of a specific user here.
  //don't forget to undo the impersonation
   undoImpersonation();
} else {
  //Your impersonation failed. Therefore, include a fail-safe mechanism here.
}

We simply need to call the impersonateValidUser method with the valid username and password to impersonate that user. From then on, until undoImpersonation() is called, we will be performing all actions as the supplied username.

Authors Note: To get impersonation working correctly under asp.net, change the processModel node in the machine.config (c:\winnt\microsoft.net\framework\v%VERSION%\config\machine.config). The username attribute must be set to "System". For more information regarding this change please see the security documentation on MSDN.

Conclusion

These are the essentials needed to complete a fully functioning DAL for AD for any provider with the System.DirectoryServices namespace. Take this sample, and adapt it to your needs. Keep in mind that for any DAL to be really useful, it should not be limited to a single provider, including your normal database providers. You should be able to swap in a DAL that uses SQL Server to maintain the database of users and remove the AD DAL entirely.