As you venture into this aspect of development, you will likely use 1 of 2 assemblies to provide you access to Active Directory (AD) or other directory services providers (DSP's). Microsoft's System.DirectoryServices is the most fundamental - providing core LDAP (lightweight directory access protocol) access to AD and its schema/components. The other is Microsoft's Active Directory Services Interface assembly (ADSI) - the ActiveDs.DLL - which is not so documented but provides a hoard of features for directory services development.
Here I am going to introduce some basic fundamentals/concepts in an effort to help you understand how these core components interact with AD from your application. In my travels down this path I have found very little in News Groups, on TechNet, or in the development community in general that address the basic fundamentals: Most of my findings are support snipets that assume you understand a lot of core components/constructs already. Most people however, do not.
As this series continues, we will cover basic AD interfaces that allow your application to interact with AD, users and objects, and update / maintain these objects. We'll gradually venture into more complex topics like security and Access Control Entries (ACE's) and Access Control Lists (ACL's) - which are the underlying interfaces/components that will provide you the ability to deliver directory services applications feature-rich in functionality and utility.
The only assumptions we'll make here are:
- You are familiar with Visual Studio and basic development practices.
- You understand what assemblies / references are in the IDE / application projects.
- You are comfortable with the C# language and .Net in general.
Finally, this is not a definitive guide or approach - it is simply the musings of another Geek in Need - and I hope that conveying some of this knowledge is helpful to other developers.
So let's begin!!!
System.DirectoryServices Namespace
At the core of this namespace is the primary class DirectoryEntry. There is more here than we will cover for now, but I want to start off simple.
DirectoryEntry is the class you'll use to connect to AD, modify properties, rename or move an AD object, enumerate child objects, create child objects, delete child objects, and collect properties on objects in AD.
For this review, we'll use an AD server I have that has a DNS of developer.hamilton.com, and it is important to note the domain name components here. DirectoryEntry uses specific naming identifiers to bind and interact with directory services components. Here are some we'll address initially:
- OU - organizationalUnitName, or organizational unit. Note however, how I spelled the initial name - using Camel Case and the fully qualified name. Throughout this series it is important to note this convention as AD uses property names in this fashion - and we will get into that in later parts.
- CN - commonName - or cononical name. Examples are Mike Hamilton. In directory services this object is references as CN=Mike Hamilton. We'll cover this more shortly.
- DC - domainComponent. Remember the server name above? Fully qualifying a reference to this in a binding to a DirectoryEntry is DC=developer,DC=hamilton,DC=com. I'll cover more on this in a moment too.
Lets say that Mike Hamilton is a user in AD, in the Users OU on the developer.hamilton.com domain. The following is a general reference in how you would qualify this binding in DirectoryEntry:
LDAP://developer.hamilton.com/CN=Mike Hamilton,OU=Users,DC=developer,DC=hamilton,DC=com
When binding with LDAP (or directory services) you'll notice that the connection string (for lack of a better way to describe it) is in a reverse tree order. If you were to browse this entry with Active Directory Users & Computers, you would expand developer.hamilton.com as the root node, then expand Users, and finally you would see all of the user objects in that node. If I were to create my domain user accounts in an Accounts OU, and further quantify the user objects by department (like Accounting, Development, etc). I might have something more like:
developer.hamilton.com as the root, with an OU off the root called Accounts, and within Accounts I would create OU's called Accounting, and another called Development. Now, lets say that Mike Hamilton is in the Development OU. The connection string would look like:
LDAP://developer.hamilton.com/CN=Mike Hamilton,OU=Development,OU=Accounts,DC=developer,DC=hamilton,DC=com
Now, lets look at a simple C# implementation that will bind and create a DirectoryEntry object reference to this account:
using System;
using System.DirectoryServices;
using System.Collections;
namespace DirectoryServicesAtWork
public class DirectoryUtility
{
private DirectoryUtility()
{
DirectoryEntry userEntry = new DirectoryEntry(”LDAP://developer.hamilton.com/CN=Mike Hamilton,OU=Developers,OU=Accounts,DC=developer,DC=hamilton,DC=com”);
}
}
Yes, this is a very simple example, but the above code creates an object reference called userEntry and this object will now allow you to inspect, change, and save changes to properties of the user account Mike Hamilton.
ACTIVE DIRECTORY PROPERTIES
There are a host of properties associated with objects in AD. And if you are working with a Windows 2003 forest, there are even more that were added to 2003. For now, I will review a few fundamental ones and demonstrate interaction with those properties.
Lets say I want to get the AD user ID, full name, company name, telephone number and email address of the Mike Hamilton object to display on a form? For this example, we will not create a form or the controls for this display. You will notice the textbox control references easily enough. The purpose here is to give you an example of the syntax and how to reference the appropriate properties.
There are many properties in AD, but we are going to work with only a few for now. As we get into other parts we will review more properties and how to interact with those.
Get User ID, Full Name, Company Name, Telephone Number, and Email Address.
using System;
using System.DirectoryServices;
using System.Collections;
using System.Text;
using System.Forms;
using System.ComponentModel;
namespace DirecetoryUtility
public class frmMain : System.Windows.Forms.Form // This is the form we'll display our data on...
{
// Here we'll skip the normal references to our controls (text boxes, etc.)
public frmMain()
{
InitializeComponent();
DirectoryEntry userEntry = new DirectoryEntry(”LDAP://developer.hamilton.com/CN=Mike Hamilton,OU=Developers,OU=Accounts,DC=developer,DC=hamilton,DC=com”);
if (userEntry!=null)
{
txtUserID.Text = userEntry.Properties[”displayName”].Value.ToString();
txtFullName.Text = userEntry.Properties[”givenName”].Value.ToString()+” “+userEntry.Properties[”sn”].Value.ToString();
if (userEntry.Properties[”companyName”].Value.ToString()!=null)
txtCompanyName.Text = userEntry.Properties[”companyName”].Value.ToString();
if (userEntry.Properties[”telephoneNumber”].Value.ToString!=null)
txtPhoneNumber.Text = userEntry.Properties[”telephoneNumber”].Value.ToString();
if (userEntry.Properties[”mail”].Value.ToString()!=null)
txtMail.Text = userEntry.Properties[”mail”].Value.ToString();
} // End if statement
} // end frmMain
} // End class
Again, this is a very simple example, but it touches on some very important aspects - Property Names in the directory.
Active Directory properties can be a single value, or a collection (array) of values for the property. For example, the userAccountControl property is an enumeration of values that maintain the account status (i.e. Disabled, User Must Change Password, Password Never Expires, and more). We will get more into properties in Part 2 of this feed.
SUMMARY
Here we have only scratched the surface of Directory Services. In the next lesson we will review more in depth the properties of AD DirectoryEntry objects, and how we can manipulate these properties for one purpose or another. We will create a sample application that displays users in a given OU, and allows you to select one from the display and view/modify the properties of that user object.