I also described how to use LDAP-Queries in Saved Queries, DSQuery and in VB-Scripts in the german Magazine IT-Administrator 01/2005 in the article "Neue Möglichkeiten zur Administration

Understand LDAP-Queries

Active Directory is a Directory Service which allows to be queried via the Lightweight Directory Services Protocoll (LDAP). Many Applications and administrative Tools are using that protocol. Those might be applications for portals, Voice-over-IP, WebSites and Web-Applications, or other applications which are directory integrated or enabled. In every of my Active Directory-migrations I had to integrate 3rd-Party applications into the directory or write programs, WebSites or scripts which queried or modified the Active Directory via LDAP. Coming with Windows Server 2003 and the "Saved Queries"-Feature Administrators have a very powerfull tool built into the GUI for finding or modifying all Objects which meet specific conditions, such as being locked out users, being disabled, their homedrive is on the same server, they share the same phonenumber a.s.o. To use all those possibilities it is necessary that the Administrator understands how LDAP-Queries are built.

I will describe the basic elements of a LDAP-Query on this page - the more you practice and get yourself used to LDAP-Queries the more usefull they will be to easy your daily administrative tasks.

Build the base - understand the "Distinguished Name"

To form LDAP-Queries it is important to understand what a Distinguished Name is. The Distinguished Name (DN) describes the Object and where it is located in the directory. In the example-domain in the picture below a useraccount "John Doe" could have the distinguished name cn=John Doe, ou=New York, ou=My Corp Users, dc=company, dc=com. The first part of the DN (until the first comma) is the name of the object, and the other parts which are also parted by a comma describe the parent containers or organisational units (OUs). Most objects are referenced by their "common name (cn)" that is the reason for the cn= in front of the objects name. One exception to the rule are organisational units, which are referenced by their acrynom ou. Another excetion is the "domain component (dc)". This one describes the domain, the parts of the DNS Fully Qualified Domain Name (FQDN) are separated by dc=, e.g. dc=company, dc=com for die domain "company.com" or dc=us, dc=company, dc=com for its subdomain "us.company.com".

Note:Being aware of OUs and containers you will recognize that the containers like "Users" or "Computers" (which are automatically created when installing Active Directory) are not OUs but containers.
The main difference between OUs and containers is that you are able to link Group Policy Objects (GPOs) to OUs. You wouldn't be able to link them to containers.
If you use the default-Path for users the distinguishedName of John would be cn=John Doe, cn=Users, dc=company, dc=com.

Many searches against the AD are retrieving the attribute distinguishedName. You need the DN to modify or move Objects, so many times the search is first locating the object and them perform further actions once the DN is known.

Searchbase

The Seachbase describes the root of the search: which object (and maybe the objects underneath) should be searched. For example if you are searching for specific users, and you have all useraccounts in the default container cn=Users you will define the searchbase as cn=Users, dc=company, dc=com (with your domainname).

Attention:Some vendors of 3rd-party applications might try to tell you that the searchbase needs to be the domain (in this example dc)company, dc=com) or the Users-Container (cn=Users, dc=company, dc=com). Verify which kind of search the application performs. Many applications are just looking for useraccounts. Seaching the whole domain will also return accounts like builtin accounts, administrative accounts or service accounts which are not mostly not needed or wanted. In the other case if you have your users underneath your own OUs (which is most often done) a search against the searchbase cn=Users,... will not return your useraccounts.
Verify closely what the application really needs. A OU-Structure is usually designed based on the needs for administrative delegations and to apply GPOs, and I would mostly not recommend to redesign the structure because of a appication.
If you want to know what queries the application performs ask the vendor and verify using a network monitor (as long as there's no server-certificate deployed to the DC the LDAP-Queries and responses are mostly unencrypted.

Scope

The Scope defines which hierarchies are to be searched. The following scopes are possible:

Attribute

You are able to define which attributes you want to retrieve in the result of the search. For example you can request to retrieve the distinguishedName, the sAMAccountID (which is the pre-Windows Logonname), givenname or surname (sn).

Searchfilter

The most important parameter of the search is the filter. It describes what to search. The filter is built out of different search-criterias, which consist out of the attribute to search, the operator to compare and the value to look for. If you want to look for object with the givenname "John" the search-criteria woule be givenname=John.

Mostly you will be going to search for multiple criterias. Looking for John you are not going to search for groups or computers named John, you want to make sure that you just retrieve useraccounts. Therefore you are able to embrace search-criterias and use operators to combine them. The operator is supposed to be in front of the search-criterias it combines, and you are able to stack braces. Here are a few examples for operators:

Additional you are able to use the wildcard "*", sn=D* will return all object with a surname (sn) beginning with M. But it is strongly recommended to use the wildcard at the beginning or in the middle of a value because the directory services is not optimized for those queries and will take a long time (and the preformance of the Domaincontroller fullfilling the query will decrease).

Note:When searching for useraccounts in Active Directory it is recommended always to include the filter "(&(objectCategory=Person)(objectClass=User))". The reaons for that filter is that objectCategory=Person is a single value but also contains contacts and computeraccounts. On the other hand you can be sure that a object which objectClass=User is a useraccount, but this attribute contains multiple values and a search against it without further limitations would not perform very well.

More complex filters: Search attributes bitwise

There are attributes in Active Directory which are calculated and every bit has a different meaning. A very popular example for such an attriute is "useraccountcontrol". Therefore there's a possibility to search attributes bitwise. To perform such a search you have to use an additional search-criteria, the ruleOID. You construct the search-criteria containing the bitwise search like attributname:ruleOID:=value. There are two ruleOIDs you can use:

For example, if you want to perform a search against all useraccounts which are disabled (the second bit of userAccountControl is set) you are able to use the following filter:
(&(objectCategory=Person)(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))

More Details on performing bitwise searches and a VB-Script Example is mentioned in the following Knowledgebase-Article:

269161 How To Query Active Directory By Using a Bitwise Filter
http://support.microsoft.com?id=269161

Tipps



You are welcome to E-Mail comments, feedback or general Problems with this WebSite to the  WebMaster. The WebSites of WindowsServerFAQ.de and/or WindowsServerFAQ.org are not related to Microsoft Corp. USA or to Microsoft GmbH. Copyright 2004. ALL RIGHTS RESERVED. You have to accept the Disclaimer and the legal Annotations to use the WebSites of WindowsServerFAQ.de or WindowsServerFAQ.org.