Detecting Nested Objects in Active Directory with PowerShell

Overview of Script

The purpose of this PowerShell script is to recursively query Microsoft.ActiveDirectory.Management.ADObjects in an Active Directory security group. This can be useful when you have nested security groups, but you want to extract the user object at all depths. I came across this issue at work and I initially used a loop, but identifying when to use recursive functions can become a tool in itself even if you don’ have a degree in computer science.

Assembling our Script

Defining our Script Parameters

We are going to use Script Parameters that we pass in when we call our script.

param (
    [Parameter(Mandatory=$true)]
    [Alias("name")]
    [string] $groupName,

    [switch] $groupsOnly
)

Error Catching and Verbose Output

In this section of the code, I want to import the ActiveDirectory PowerShell module and validate the group exists in the domain by using the Get-ADGroup cmdlet. We use the LDAP filter instead of -Identity parameter to check if the group exists without causing any errors.

Import-Module ActiveDirectory
$domainName = (Get-ADDomain).DNSRoot

Write-Output ("`nDetecting nested objects in {0} for {1} group`n" -f $domainName, $groupName)

try{
    if($null -eq (Get-ADGroup -Filter "Name -eq '$groupName'")){
        throw "$groupName does not exist on $domainName"
    }
}catch{
    Write-Error $_.Exception.Message; exit 1
}

Recursive Function to Detect Nested ADObjects

The function Get-NestedGroupMembers recursively retrieves members of a specified Active Directory group $gn. It iterates through each member and categorizes them based on their object class. If a member is a group, it displays its name as a “Nested Group” and recursively calls the function to retrieve its members. If a member is a user, it displays the user’s SamAccountName unless the switch parameter $groupsOnly is present. If the object class is unknown, it notifies the user accordingly.

function Get-NestedGroupMembers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [string] $gn
    )
    $members = Get-ADGroupMember -Identity $gn
    foreach($obj in $members){

        switch ($obj.objectClass) {
            "group" {
                Write-Output ("Nested Group: {0}" -f $obj.Name)
                Get-NestedGroupMembers -gn $obj.Name
            }
            "user" {
                if( -not ($groupsOnly.IsPresent)){
                    Write-Output ("User: {0}" -f (Get-ADUser $obj -Properties UserPrincipalName).SamAccountName)
                }
            }
            default {
                Write-Output ("Unknown object class: {0}" -f $obj.objectClass)
            }
        }
    }
}
Get-NestedGroupMembers -gn $groupName

Completed Script

Here is the complete script for you to use and modify in your environment.

param (
    [Parameter(Mandatory=$true)]
    [Alias("name")]
    [string] $groupName,

    [switch] $groupsOnly
)

    Import-Module ActiveDirectory
    $domainName = (Get-ADDomain).DNSRoot

    Write-Output ("`nDetecting nested objects in {0} for {1} group`n" -f $domainName, $groupName)

    try{
        if($null -eq (Get-ADGroup -Filter "Name -eq '$groupName'")){
            throw "$groupName does not exist on $domainName"
        }
    }catch{
        Write-Error $_.Exception.Message; exit 1
    }
    
function Get-NestedGroupMembers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [string] $gn
    )
    $members = Get-ADGroupMember -Identity $gn
    foreach($obj in $members){

        switch ($obj.objectClass) {
            "group" {
                Write-Output ("Nested Group: {0}" -f $obj.Name)
                Get-NestedGroupMembers -gn $obj.Name
            }
            "user" {
                if( -not ($groupsOnly.IsPresent)){
                    Write-Output ("User: {0}" -f (Get-ADUser $obj -Properties UserPrincipalName).SamAccountName)
                }
            }
            default {
                Write-Output ("Unknown object class: {0}" -f $obj.objectClass)
            }
        }
    }
}
Get-NestedGroupMembers -gn $groupName

Conclusion

This simple script can be useful when you need to find users being targeted by a group policy and you’re using a security group for item-level targeting. You can even output the users or nested groups into a CSV file or modify the output stream and make it more verbose. All-in-all, I hope you learned something from this post. My goal is to simply share ideas and you should expand on them. Please leave a comment or Contact Me!