Active Directory UDF - GetObjectsInOU

Function _AD_GetObjectsInOU is the swiss army knife of the Active Directory UDF.
It allows to search for whatever criteria you specify and returns whatever properties you want.

Parameters

The following parameters define what is searched for and what properties are returned by the function:

$sOU

The Active Directory container where to begin the search.

$sFilter

The LDAP filter defines what to search for. More details can be found in the next section.

$iSearchScope

Defines the search constraints. The following constraints are supported:

Base:

You search only the so-called “base” object (that is, the Active Directory container where you begin your search as defined by $sOU); child containers are not searched. The base search is useful when you want to pull out information for a single OU (for example, a list of all the user accounts in the Finance OU).

Set the parameter to 0 to use this contraint.

One Level:

A one-level search is restricted to the immediate children of a base object, but excludes the base object itself. A one-level search can be used to enumerate all children of an object.

Set the parameter to 1 to use this contraint.

Subtree:

The entire subtree is searched: that includes the base container, all sub-containers and any containers contained within those sub-containers. A subtree search is normally used to search objects for a given scope. For example, search for all users with accounts that will expire in 30 days or less.

Set the parameter to 2 to use this contraint. This is the default value.

For more information please check this site [1].

$sDataToRetrieve

A comma separated list of properties to be returned for each object that matches the search criteria.

$sSortBy

A single property the resulting records will be sorted by. This has to be one of the properties specified in $sDataToRetrieve.

LDAP filter

The best description how to create a LDAP filter can be found here [2].

Remarks

• Multi-value attributes are returned as a string with the pipe character (|) as separator.
• To make sure that all properties you specify in $sDataToRetrieve exist in the AD you can use _AD_ObjectExistsInSchema.
• This function returns the selected properties "as is". To "decode" unreadable properties you need to use function _AD_GetObjectProperties.
• If you need a single property of a single object you can use function _AD_GetObjectAttribute. Note: This function returns the property "as is" (undecoded) as well.

Examples

List all Group Policies:

$aObjects = _AD_GetObjectsInOU("", "(objectClass=groupPolicyContainer)", 2, "displayName,gPCFileSysPath")

Users that have never logged on before:

$aObjects = _AD_GetObjectsInOU("", "(&(&(objectCategory=person)(objectClass=user))(|(lastLogon=0)(!(lastLogon=*))))", 2, "sAMAccountName,distinguishedName,displayname")

Users that must change their password the next time they logon:

$aObjects = _AD_GetObjectsInOU("", "(&(objectCategory=person)(objectClass=user)(pwdLastSet=0))", 2, "sAMAccountName,distinguishedName,displayname")

Get Bitlocker recovery information object for the current computer.

Note that you need elevated permissions, the query doesn't work for ordinary users. For more information please check the following site. More detailed information can be derived using the following script.

$sAD_OU = _AD_SamAccountNameToFQDN(@ComputerName & "$")
$aResult = _AD_GetObjectsInOU($sAD_OU, "(objectcategory=msFVE-RecoveryInformation)", 2 , "distinguishedname")
_ArrayDisplay($aResult, "FQDN for the Bitlocker Recovery Information objects")
$aResult = _AD_GetObjectProperties($aResult[1])
_ArrayDisplay($aResult, "All properties of the first Bitlocker Recovery Information object")