From authenticating application users against Active Directory, to programmatically adding users to Active Directory groups, it seems that a developer in a Microsoft supported environment is never too far away from Active Directory. At least this has been true in my experience. In recent years, there have been many times when I’ve needed to read or modify values in an Active Directory repository. Each time, I’ve found myself going back to previous projects or resorting to internet searching, in order to re-learn the steps and components involved.<\/p>\n
Eventually, I decided to build a .NET library containing wrappers and components that would allow me to interact with Active Directory without having to remember each time how everything in the System.DirectoryServices<\/b> namespace works.<\/p>\n
This article will explain pieces of this library by walking through how to convert four commonly used Active Directory data types into data types that can be used in a .NET application. It will also explain how to:<\/p>\n
The source code for this article (see the Code Download link in the box to the right of the article title) contains the full .NET 2.0 solution, written in Visual Basic.NET. This solution contains two projects: A class library called SimpleTalk_ADDataWrappers<\/b> which contains the four wrapper classes mentioned above and a console application called TestConsole<\/b> which retrieves a user from an Active Directory repository and demonstrates how each of the four wrappers can be used. In this article, the wrapper objects and the console application are explained in detail.<\/p>\nThe problem with values in Active Directory<\/h2>\n
At first glance, building this library seemed pretty easy, but I quickly hit my first road block. When you retrieve an object from Active Directory there are no strong typed properties or intellisense to help you get to the information you need. For example, you can’t type user.displayName<\/b> to get the string representing the user’s display name. Once you get the user object from the repository, you would access the user’s display name as user.properties(“displayName”)<\/b> which returns an array of objects. So, not only do you have to know that there is a property on the user object called displayName<\/b> but also what data type you’re expecting it to return, and whether you should expect multiple values or just need to look at the first position in the array.<\/p>\n
Having finally mastered displayName<\/b>, what if you wanted to know when the user had last logged onto the network. You would start by getting the property named lastLogOn<\/b> which will also return an array of objects. However, the returned data type is a COM object of type Interop.ActiveDs.IADsLargeInteger<\/b> which is a large integer object with a high and low part representing a date and time. To make easy use of this data it would need to be converted into a Date<\/b> object, and if you wanted to save it back to the repository it would need to be converted back again.<\/p>\n
Aside from IADsLargeInteger<\/b>, there are three more values that are returned from Active Directory that require some sort of conversion if you want to leverage them in a .NET application:<\/p>\n First, let’s look at how to convert the IADsLargeInteger<\/b> into something that can be easily used.<\/p>\n The ADDateTime<\/b> class in our .NET 2 library wraps the IADsLargeInteger<\/b> object. Several Active Directory schema properties including accountExpires<\/b>, <\/i>badPasswordTime<\/b>, <\/i>lastLogon<\/b>, <\/i>lastLogoff<\/b> <\/i>and passwordExpirationDate<\/b> <\/i>return IADsLargeInteger<\/b> values, all of which can be wrapped using the ADDateTime<\/b> object.<\/p>\n The wrapper exposes the following three members.<\/p>\n The constructor for the wrapper is straight forward and accepts the IADsLargeInteger<\/b> value from the Active Directory repository.<\/p>\n This read-only property is also fairly straight forward. It exposes the IADsLargeInteger<\/b> and is used for getting the value back from the wrapper when saving it to the repository.<\/p>\n This property exposes the ADsLargeInteger<\/b> value as a standard .NET DateTime<\/b> object. The conversions to the underlying IADsLargeInteger<\/b> are done when the property is invoked (both getting and setting) ensuring that the latest version of the IADsLargeInteger<\/b> will be returned when reading this property, as well as when invoking the read only ADsLargeInteger<\/b> property.<\/p>\n The code for the StandardDateTime() <\/b>property is listed below:<\/p>\n Public Property StandardDateTime() As DateTime \u00a0\u00a0\u00a0\u00a0\u00a0 Return Me.IADsLargeIntegerToDateTime(Me._ADLI)<\/p>\n \u00a0\u00a0 End Get \u00a0\u00a0\u00a0\u00a0\u00a0 Me._ADLI = Me.DateTimeToIADsLargeInteger(Value)<\/p>\n \u00a0\u00a0 End Set The private member _ADLI<\/b> is the underlying IADsLargeInteger<\/b> value. The two methods that this property uses are private methods of the ADDateTime<\/b> class. These methods convert between IADsLargeInteger<\/b> values <\/i>and standard DateTime<\/b> objects using calls to unmanaged code, and can be found in the source code region IADsLargeInteger CONVERSION METHODS<\/b>.<\/p>\n The ADObjectGuid<\/b> object wraps identifier byte arrays returned from Active Directory. Every schema object in Active Directory, including users and groups, is uniquely identified using a string of bytes. This value is returned by the Active Directory schema property objectGuid<\/b>. Because the identifier values should not be modified, only read only properties are exposed on this class. The ADObjectGuid<\/b> opbject exposes four members. Firstly, the constructor accepts the 128 bit byte array returned from the Active Directory repository.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0 Sub New(ByVal bytes As Byte())<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Me._bytes = bytes<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0 End Sub<\/p>\n The read only property, bytes<\/b>, returns the byte array as it was passed into the constructor.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0 Public ReadOnly Property bytes() As Byte() The read only property, guid<\/b>, returns the byte array in the form of a Guid<\/b>.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0 Public ReadOnly Property guid() As Guid The read only property, splitOctetString<\/b>, returns the identifier byte array as an octet string with each byte displayed as a hexadecimal representation and delimited by a ‘\\<\/strong>‘ character. This format is required when using the System.DirectoryServices.DirectorySearcher<\/b> to search for Active Directory objects by the objectGUID<\/strong> schema property.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0 Public ReadOnly Property splitOctetString() As String \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Dim iterator As Integer \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 builder = _ \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Return builder.ToString()<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Get The ADObjectSid<\/b> object is used to wrap the value of an Active Directory object’s objectSid<\/b> schema property. It is very similar to the ADObjectGuid<\/b>. In fact, they both have the same constructor and all of the same properties, except ADObjectSid<\/b> does not have a guid<\/b> property. That’s because the object’s SID byte array is 224 bits instead of 128 and cannot be converted to the Guid<\/b> data type. When an Active Directory object is created, it is assigned a SID value by the system. This value can subsequently be changed by the system but once it changes the system will never again reuse the old value with a different object. Old values are stored in the object’s schema property, sidHistory<\/b>, which returns an object array of SID byte arrays.<\/p>\n Like the ADObjectGuid<\/b>, the splitOctetString<\/b> property of the ADObjectSid<\/b> can also be used in search filters when searching for objects by the object’s SID value. This value is also often used when searching for objects by association as the association often references this value.<\/p>\n The ADUserAccountControl<\/b> object wraps the value of the Active Directory schema property, userAccountControl<\/b>. The value is simply an integer that represents several different common account control flags. Once you know what the flags are and their values, you only need to perform bitwise operations on the value to set the flag or see if the flag is set. The following snippet from the ADUserAccountControl<\/b> class is the enumeration of the available flags with their values.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Public Enum enumUserAccountControlFlag Most of the rest of the class contains public properties, one for each flag above, to set the flag or see if the flag is set. As an example, below, is the code for the LOCKED_OUT<\/b> property.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Public Property accountLockedOut() As Boolean The bitwise operations actually take place in two convenience methods that can be seen used above:<\/p>\n Every other flag property of the ADUserAccountControl <\/b>class is implemented this way as well.<\/p>\n The TestConsole<\/b> project included with this article explains how a user can be retrieved from an Active Directory repository, and how the wrapper objects examined above can be leveraged to make useful information out of the data returned from the user’s schema properties.<\/p>\n The TestConsole<\/b> project has the following three references (beyond the default references included when the project is first created):<\/p>\n The Main<\/b> method of the TestConsole<\/b> application starts by setting up some configuration variables that will be used during the execution.<\/p>\n Dim repositoryPath As String = “LDAP:\/\/yourRepositoryPathGoesHere” The repositoryPath<\/b> string will specify the path to your Active Directory repository. The username<\/b> string contains the domain username of the user you are going to query. The filter<\/b> specifies the “query”, if you will, that will be executed to find this user. The ADUsername<\/b> and ADPassword<\/b> strings specify the credentials for the user that will be used when binding to the user entry that you are searching for in the Active Directory repository.<\/p>\n In the typical domain environment, your domain credentials will give you access to bind to your own user object entry in the Active Directory repository. In other words, depending on your domain’s security settings, you may not have access to query any other username in the repository but your own. Therefore, if you run into any problems running the example code, try setting the value of username<\/b> to your domain username and the values for ADUsername<\/b> and ADPassword<\/b> to your domain username and password.<\/p>\n NOTE<\/b>: Once the configuration variables have the correct values, the application can initialize the directory service objects.<\/p>\n Dim repositoryRootEntry As New _ Dim directorySearcher As New _ The repositoryRootEntry<\/b> will be the starting location in the search. In my case, when I instantiated the repositoryRootEntry<\/b>, I passed in the path to the root of my domain’s Active Directory tree and the administrator’s username and password. The directorySearcher<\/b> is used in executing searches against an entry, in our case the repositoryRootEntry<\/b> using the specified filter.<\/p>\n Next, the application executes the search by invoking the directorySearcher<\/b>‘s FindOne<\/b> method to return a DirectoryServices.SearchResult<\/b> object:<\/p>\n Dim result As DirectoryServices.SearchResult = _ The directorySearcher<\/b> also exposes a FindAll<\/b> method which returns a DirectoryServices.SearchResultCollection<\/b>. The FindOne<\/b> method is used in this case because there is only one user in the repository that has the specified username<\/b>. So, if the number of return results can be expected to be only one, the FindOne<\/b> method can be used, otherwise use FindAll<\/b>. Also, note that the rest of the code is wrapped in a Try\/Catch block, because from this point on if anything is going to go wrong it will happen once the connection to the repository is made.<\/p>\n If the result is not null, then the directorySearcher<\/b> succeeded in finding the user, which will be returned as a DirectoryServices.DirectoryEntry<\/b>.<\/p>\n Dim user As DirectoryServices.DirectoryEntry = result.GetDirectoryEntry<\/p>\n The remaining four method calls test the four wrapper methods described earlier in the article. Since they are all similar, let’s look at the testADObjectGuid<\/b> in detail.<\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ‘ object guid It may look like more code than necessary, but that’s because the ControlChars<\/b> end up bloating the Console.WriteLine<\/b> lines. First, the value is retrieved using another method in the module, getProperty<\/b>, which takes the user<\/b> DirectoryEntry <\/b>and the name of the property to retrieve, in this case, objectGUID<\/b>. If getProperty<\/b> returns nothing then a message is printed. Otherwise, the value<\/b> object is loaded into a new ADObjectGuid<\/b> wrapper object. Finally, the method writes the Guid<\/b> and the split octet string representations of the identifier to the console.<\/p>\n The getProperty <\/b>function is used to retrieve the value because it takes a few lines of code to get just one value from an entry. That’s because, as mentioned earlier, when you request a property from a DirectoryEntry<\/b> it returns an array of objects. All of the properties being requested in this module are only expected to return one value. So, this function extracts that value from the first index of the array returned. The code for the getProperty <\/b>function is listed below.<\/p>\n \u00a0\u00a0\u00a0 Private Function getProperty _ Notice that before the function actually requests the value from the directoryEntry<\/b>, it first checks to see if the entry contains the property. Although the schema may support a property on the entry, if the entry doesn’t have a value for that property, it won’t exist.<\/p>\n The properties that the entry has values for can be obtained by invoking DirectoryEntry.Properties.PropertyNames<\/b>, which is an array of strings representing the property names of the properties that have values for the specific entry. There are actually several hundred properties available for many types of DirectoryEntry <\/b>objects. A list of the properties can be obtained programmatically including information about which properties are mandatory and which are optional. However, this being outside of the scope for this article, to find out more information go to:<\/p>\n\n
IADsLargeInteger wrapper<\/h2>\n
\n
\n
\n
<\/pre>\n
\n\u00a0\u00a0 Get<\/p>\n
\n\u00a0\u00a0 Set(ByVal Value As DateTime)<\/p>\n
\nEnd Property<\/p>\nObjectGuid wrapper<\/h2>\n
<\/pre>\n
<\/pre>\n
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Get
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Return Me._bytes
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Get
\n\u00a0\u00a0\u00a0\u00a0\u00a0 End Property<\/p>\n<\/pre>\n
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Get
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Return New Guid(Me._bytes)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Get
\n\u00a0\u00a0\u00a0\u00a0\u00a0 End Property<\/p>\n<\/pre>\n
\n\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0Get<\/p>\n
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Dim builder As StringBuilder
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Dim values() As Byte = Me._bytes<\/p>\n
\n\u00a0\u00a0\u00a0 New StringBuilder((values.GetUpperBound(0) + 1) * 2)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 For iterator = 0 To values.GetUpperBound(0)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 builder.Append(“\\” & values(iterator).ToString(“x2”))
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Next<\/p>\n
\n\u00a0\u00a0\u00a0\u00a0\u00a0 End Property<\/p>\nObjectSid wrapper<\/h2>\n
UserAccountControl wrapper<\/h2>\n
<\/pre>\n
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 SCRIPT = &H1
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ACCOUNT_DISABLED = &H2
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 HOMEDIR_REQUIRED = &H8
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 LOCKED_OUT = &H10
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 PASSWD_NOT_REQD = &H20
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 PASSWD_CANT_CHANGE = &H40
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ENCRYPTED_TEXT_PASSWD_ALLWD = &H80
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 TEMP_DUPLICATE_ACCT = &H100
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 NORMAL_ACCOUNT = &H200
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 INTERDOMAIN_TRUST_ACCT = &H800
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 WORKSTATION_TRUST_ACCT = &H1000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 SERVER_TRUST_ACCT = &H2000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 PASSWD_NO_EXPIRE = &H10000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 MNS_LOGON_ACCT = &H20000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 SMART_CART_REQD = &H40000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0TRUSTED_FOR_DELEGATION = &H80000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 NOT_DELEGATED = &H100000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 USE_DES_KEY_ONLY = &H200000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 PREAUTH_NOT_REQD = &H400000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 PASSWD_EXPIRED = &H800000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 TRUSTED_TO_AUTH_FOR_DELEGATION = &H1000000
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Enum<\/p>\n<\/pre>\n
\n\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0Get
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Return Me.isFlagSet(enumUserAccountControlFlag.LOCKED_OUT)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Get
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Set(ByVal value As Boolean)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Me.updateFlag(enumUserAccountControlFlag.LOCKED_OUT, value)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Set
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End Property<\/p>\n\n
Using the wrapper classes<\/h2>\n
\n
<\/pre>\n
\nDim username As String = “usernameOfUserToQuery”
\nDim filter As String = _
\n“(&(objectClass=user)(sAMAccountName=” & username & “))”
\nDim ADUsername As String = “ADUsername”
\nDim ADPassword As String = “ADPassword”<\/p>\n
\nIt’s worth mentioning at this point that although rare, depending on your domain’s security settings, this application may not work at all for your credentials. If you continue to experience problems after a tweaking the configuration variables a few times, you may need to contact your system administrator to gain the necessary access.<\/em><\/p>\n<\/pre>\n
\nDirectoryServices.DirectoryEntry(repositoryPath, _
\nADUsername, ADPassword)<\/p>\n
\nDirectoryServices.DirectorySearcher(repositoryRootEntry, filter)<\/p>\n<\/pre>\n
\ndirectorySearcher.FindOne()<\/p>\n<\/pre>\n
<\/pre>\n
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Dim value As Object = getProperty(user, “objectGUID”)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 If Not value Is Nothing Then
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Dim wraper As New ADObjectGuid(value)
\nConsole.WriteLine(“User’s Guid Identifier:” & _
\nControlChars.Tab & ControlChars.Tab & _
\nControlChars.Tab & wraper.guid.ToString)
\nConsole.WriteLine(“User’s Split Octet Identifier:” &_
\nControlChars.Tab & ControlChars.Tab & wraper.splitOctetString.ToString)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Else
\nConsole.WriteLine(“Something is wrong – this user has no unique identifier.”)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 End If<\/p>\n<\/pre>\n
\n(ByVal user As DirectoryServices.DirectoryEntry, _
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ByVal propertyName As String) As Object
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0 If user.Properties.Contains(propertyName) Then
\nDim properties As _ DirectoryServices.PropertyValueCollection = _
\nuser.Properties(propertyName)
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Return properties(0)
\n\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0End If
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Return Nothing
\n\u00a0\u00a0\u00a0 End Function<\/p>\n