Skip to content

Get-ADTreeGroupMember.md

Latest commit

 

History

History
379 lines (264 loc) · 11.1 KB

Get-ADTreeGroupMember.md

File metadata and controls

379 lines (264 loc) · 11.1 KB
external help file PSADTree.dll-Help.xml
Module Name PSADTree
online version https://github.com/santisq/PSADTree/blob/main/docs/en-US/Get-ADTreeGroupMember.md
schema 2.0.0

Get-ADTreeGroupMember

SYNOPSIS

Displays Active Directory group members in a tree-like structure, including nested members and circular group detection.

SYNTAX

Depth (Default)

Get-ADTreeGroupMember
    [-Identity] <String>
    [-Server <String>]
    [-Credential <PSCredential>]
    [-Depth <Int32>]
    [-ShowAll]
    [-Group]
    [-Exclude <String[]>]
    [-Properties <String[]>]
    [<CommonParameters>]

Recursive

Get-ADTreeGroupMember
    [-Identity] <String>
    [-Server <String>]
    [-Credential <PSCredential>]
    [-Recursive]
    [-ShowAll]
    [-Group]
    [-Exclude <String[]>]
    [-Properties <String[]>]
    [<CommonParameters>]

DESCRIPTION

The Get-ADTreeGroupMember cmdlet retrieves the members of an Active Directory group—including nested members—and displays them in a tree-like hierarchical structure. Group members can include users, groups, computers, and service accounts.

This format makes it easy to visualize group nesting and quickly identify circular nested groups (infinite recursion loops caused by circular membership).

EXAMPLES

Example 1: Get the members of a group

PS> Get-ADTreeGroupMember TestGroup001

By default, this cmdlet uses -Depth 3.

Example 2: Get the members of a group recursively

PS> Get-ADTreeGroupMember TestGroup001 -Recursive

The -Recursive switch retrieves all nested members regardless of depth.

Example 3: Get the members of all groups under an Organizational Unit

PS> Get-ADGroup -Filter * -SearchBase 'OU=myOU,DC=myDomain,DC=com' |
    Get-ADTreeGroupMember

You can pipe strings containing group identity to this cmdlet or ADGroup objects to this cmdlet.

Example 4: Find circular nested groups

PS> Get-ADComputer -Filter * -SearchBase 'OU=myOU,DC=myDomain,DC=com' |
    Get-ADTreeGroupMember -Recursive -Group |
    Where-Object IsCircular

The -Group switch limits output to nested groups only (excluding users, computers, etc.).

Example 5: Get group members in a different domain

PS> Get-ADTreeGroupMember TestGroup001 -Server otherDomain.com

Example 6: Display hierarchy even for previously processed groups

PS> Get-ADTreeGroupMember TestGroup001 -ShowAll

By default, groups that have already been processed (to avoid redundant recursion) are marked as "Processed Group" and their subtree is not expanded.
The -ShowAll switch forces full hierarchy display for all groups.

Note

Using -ShowAll does not incur a significant performance penalty because the cmdlet caches group data internally.

Example 7: Retrieve and inspect additional properties

# Retrieve specific properties (friendly names are preserved as keys)
PS> $tree = Get-ADTreeGroupMember TestGroup001 -Properties Country, City, nTSecurityDescriptor

# View department for all user objects
PS> $tree | Where-Object ObjectClass -EQ 'user' |
    Select-Object *, @{ Name='Country'; Expression={ $_.AdditionalProperties['Country'] }}

# Retrieve all available attributes
PS> $tree = Get-ADTreeGroupMember TestGroup001 -Properties *

# Inspect the full dictionary for the first object
PS> $tree[0].AdditionalProperties   # ReadOnlyDictionary<string, object?>

Tip

  • -Properties * retrieves all available attributes from each object.
  • Use friendly names (e.g. Country → c, City → l, etc) or raw LDAP names — the key in .AdditionalProperties matches what you requested.
  • See the full list of supported friendly names in the source code LdapMap.cs

PARAMETERS

-Credential

Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as User01 or Domain01\User01, or enter a PSCredential object generated by the Get-Credential cmdlet. If you type a user name, you will be prompted to enter the password.

Type: PSCredential
Parameter Sets: (All)
Aliases: cred

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Depth

Determines the number of nested groups and their members included in the recursion. By default, only 3 levels of recursion are included. Get-ADTreeGroupMember emits a warning if the actual nesting exceeds this number.

Type: Int32
Parameter Sets: Depth
Aliases: d

Required: False
Position: Named
Default value: 3
Accept pipeline input: False
Accept wildcard characters: False

-Exclude

Specifies an array of one or more string patterns to be matched as the cmdlet enumerates child principals. Any matching principal is excluded from the output. Wildcard characters are accepted.

Note

  • Patterns are tested against the principal's .SamAccountName property.
  • When the matched principal is of type group, all child principals are also excluded from the output.
Type: String[]
Parameter Sets: (All)
Aliases: ex

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Group

The -Group switch indicates that the cmdlet should display nested group members only. Essentially, a built-in filter where ObjectClass is group.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: g

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Identity

Specifies the Active Directory group to retrieve members from. You can identify the group using one of the following values:

  • DistinguishedName
  • GUID
  • SID (Security Identifier)
  • sAMAccountName
  • UserPrincipalName

For more information, see the IdentityType enumeration.

Type: String
Parameter Sets: (All)
Aliases: DistinguishedName

Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

-Properties

Specifies one or more additional properties (LDAP attributes) to retrieve for each Active Directory object (user, group, computer, etc.) in the tree. Retrieved values are added to the read-only dictionary in the .AdditionalProperties property of each output object (TreeUser, TreeGroup, TreeComputer).

Behavior:

  • * → Retrieves all available attributes from the object.
  • One or more property names → Only properties that exist on the object and have a non-null value are included.

Supported input styles:

  • Friendly/PowerShell-style names (as in the Active Directory module), e.g., City, Country, Department, EmailAddress, PasswordLastSet, LastBadPasswordAttempt
  • Raw LDAP attribute names, e.g., l, c, department, mail, pwdLastSet, badPasswordTime, whenCreated

When a friendly name is used, the key in .AdditionalProperties matches the friendly name (not the LDAP name).

Special handling:

  • nTSecurityDescriptor → Returned as a security descriptor object (similar to Get-Acl output)
  • Large integer / FILETIME attributes (such as pwdLastSet, accountExpires, lastLogonTimestamp, badPasswordTime, etc.) → Converted to long (64-bit FileTime ticks)

Non-existent properties (e.g. Title on a computer object) are silently ignored.

Type: String[]
Parameter Sets: (All)
Aliases: prop, attrs, attributes

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Recursive

Retrieves all nested group members recursively (no depth limit).

Note

This switch and -Depth are mutually exclusive. If -Recursive is specified, -Depth is ignored.

Type: SwitchParameter
Parameter Sets: Recursive
Aliases: rec

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Server

Specifies the Active Directory server (or domain) to bind to. Valid values include:

Domain name formats:

  • Fully qualified domain name (FQDN)
  • NetBIOS name

Server formats:

  • Fully qualified server name
  • NetBIOS name
  • Fully qualified server name with port (e.g. dc01.contoso.com:3268)
Type: String
Parameter Sets: (All)
Aliases: s, dc

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ShowAll

By default, groups that have already been processed are marked as "Processed Group" and their hierarchy is not expanded (to avoid redundant output and recursion).

The -ShowAll switch forces the cmdlet to display the full hierarchy of all groups, even those previously processed.

Note

This cmdlet caches group data to query each unique group only once.
The -ShowAll switch reuses this cache to reconstruct hierarchies without additional AD queries, so it does not cause a significant performance penalty.
The default behavior (hiding processed groups) keeps output clean and focused.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: a

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters. For more information, see about_CommonParameters.

INPUTS

System.String

You can pipe strings that represent a group identity (DistinguishedName, GUID, SID, sAMAccountName, or UserPrincipalName) to this cmdlet.

Microsoft.ActiveDirectory.Management.ADGroup

ADGroup objects are also accepted (typically piped from Get-ADGroup or similar cmdlets).

OUTPUTS

PSADTree.TreeGroup

Represents an Active Directory group in the tree structure.

PSADTree.TreeUser

Represents an Active Directory user in the tree structure.

PSADTree.TreeComputer

Represents an Active Directory computer in the tree structure.

NOTES

treegroupmember is the alias for this cmdlet.

The cmdlet uses internal caching to avoid redundant queries to Active Directory and efficiently detect/handle circular group nesting.

RELATED LINKS

Principal Class

DirectoryEntry Class

Get-ADGroupMember

Get-ADGroup

Get-ADUser