Active Directory Filter Builder

Background

Recently, I got involved with a project migrating a client from On-Premise to Azure. Their Local AD wasn't the best fit for directly running the Azure AD Connect tool to push the local AD objects to Azure. So, one of the pre-migration steps was to clean up their local AD to make it compatible by updating a few fields like UPN, Mail NickName etc.

 

Problem Statement

The conflict was that they didn't want to update this for all the users in one go. They wanted to divide the users based on different departments or the same account or other attributes. So the filter needed to be dynamic.

 

If someone has worked with the LDAP filter query, it gets quite messy with all the brackets and conditions. If some of the conditions are missed, then it takes quite some time for troubleshooting the issue.

 

Solution

I came up with the solution to write a few filter wrappers around the LDAP query to make it easier to create an LDAP filter query that can be injected to the Directory Searcher object for fetching out the results. 

 

How Do LDAP Queries Work?

The LDAP Query follows Polish Notation and it normally works on the concept of the hierarchy between different criteria like AND and OR.

For example,  if the requirement is to fetch A, B, and C users, then the query would look like this. Each AND/OR can be treated as an individual criterion.

(&(objectCategory=person)(objectClass=user)(|(cn=A)(cn=B)(cn=C))

The first part would be AND condition for the objectcategory and objectclass and the second is the OR condition. So, it would follow a hierarchical pattern. 

 

Here is a good article explaining the syntax in detail.  

Filter Overview

1. ADFilterCondition Class
   The Class objects hold single LDAP conditions. For instance, it will help to build the condition like (objectCategory=person)
    
2.  ADFilter Class
   The class holds the collection of the ADfilterCondition class. 
   
   
3. ADFilterBuilder Class
   The class is the wrapper for building the filter that can be applied to the Directory Searcher object. 

All of the above classes can be found in the same code under the folder ADFilters. 

 

How to use the Wrappers? 

1. Initialize the ADFilter class with the criteria i.e AND/OR
   

   ADFilter _filter = new ADFilter(ADFilterBuilder.ADFilterExpression.AND);

2.  Add the condition to the filter using the Add() method. The add method takes in ADFiltercondition as an input parameter. 
   

   _filter.Add(new ADFilterCondition("objectCategory", ADFilterCondition.ADFilterOperators.EQUALTO, "person"));

3. Build the filter query using the ADFilterBuilder
   

   ADFilterBuilder.GetFilter(_filter,out _error);

Example 1 - Fetch All the user filter 

The below function will return the filter for all the users.

/// <summary>
        /// Returns (&(objectCategory=person)(objectClass=user))
        /// </summary>
        /// <returns></returns>
        private static string AllUserFilter()
        {
            string _filterQuery = string.Empty;
            string _error = string.Empty;

            ADFilter _filter = new ADFilter(ADFilterBuilder.ADFilterExpression.AND);
            _filter.Add(new ADFilterCondition("objectCategory", ADFilterCondition.ADFilterOperators.EQUALTO, "person"));
            _filter.Add(new ADFilterCondition("objectClass", ADFilterCondition.ADFilterOperators.EQUALTO, "user"));

            return ADFilterBuilder.GetFilter(_filter, out _error);

        }

Example 2 - Fetch the specified users. 

The below function will return the users with the specified filters. 

/// <summary>
       /// Returns (&(objectCategory=person)(objectClass=user)(|(cn=USER1)(cn=USER2)))
       /// </summary>
       /// <param name="users"></param>
       /// <returns></returns>
       private static string GetUserCollectionFilter(params string[] users)
       {
           string _filterQuery = string.Empty;
           string _error = string.Empty;

           ADFilter _childFilter = new ADFilter(ADFilterBuilder.ADFilterExpression.OR);
           users.ToList<string>().ForEach(delegate (string user)
           {
               _childFilter.Add(new ADFilterCondition("cn", ADFilterCondition.ADFilterOperators.EQUALTO, user));
           }
           );


           ADFilter _filter = new ADFilter(ADFilterBuilder.ADFilterExpression.AND,_childFilter);
           _filter.Add(new ADFilterCondition("objectCategory", ADFilterCondition.ADFilterOperators.EQUALTO, "person"));
           _filter.Add(new ADFilterCondition("objectClass", ADFilterCondition.ADFilterOperators.EQUALTO, "user"));

           return ADFilterBuilder.GetFilter(_filter,out _error);

       }

Execution

Use Directory Searcher for fetching the AD objects. 

private static SearchResultCollection GetUsers(string filter)
     {
         SearchResultCollection _searchResultCollections = null;

         using (DirectoryEntry rootEntry = new DirectoryEntry())
         {
             rootEntry.Path = $"LDAP://xyz.com:389/dc=xyz,dc=com";
             //rootEntry.Username = ;
             //rootEntry.Password = ;

             using (DirectorySearcher _searcher = new DirectorySearcher(rootEntry))
             {
                 _searcher.Filter = filter;
                 //_searcher.PageSize = 1000;

                 _searchResultCollections = _searcher.FindAll();
             }
         }

         return _searchResultCollections;
     }

Main Method

 static void Main(string[] args)
        {
            // Print All Users
            PrintResults(GetUsers(AllUserFilter()));

            // Print Sepcific Users
            PrintResults(GetUsers(GetUserCollectionFilter( "ABC" , "XYZ" )));

            Console.ReadLine();
        }

private static void PrintResults(SearchResultCollection results)
        {
            int counter = 1;
            results.Cast<SearchResult>().ToList<SearchResult>().ForEach(delegate (SearchResult result)
            {
                Console.WriteLine($" {counter++} : {result.GetDirectoryEntry().Properties["cn"]?.Value}");
            });
        }

Quick Start

The sample code is the console application. The main method in program.cs will be the best way to get started.