Skip to content

Get-ADTreePrincipalGroupMembership.md

Latest commit

 

History

History
356 lines (247 loc) · 10.8 KB

Get-ADTreePrincipalGroupMembership.md

File metadata and controls

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

Get-ADTreePrincipalGroupMembership

SYNOPSIS

Displays the group membership of an Active Directory principal in a tree-like structure, including nested groups and circular membership detection.

SYNTAX

Depth (Default)

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

Recursive

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

DESCRIPTION

The Get-ADTreePrincipalGroupMembership cmdlet retrieves the group membership of a specified Active Directory principal (user, computer, group, or service account) and displays it in a tree-like hierarchical structure.

This format makes it easy to visualize nested group membership and quickly identify circular nested groups (where a principal is indirectly a member of itself through a loop).

EXAMPLES

Example 1: Get group memberships for a user

PS> Get-ADTreePrincipalGroupMembership john.doe

By default, this cmdlet uses -Depth 3.

Example 2: Get the recursive group memberships for a user

PS> Get-ADTreePrincipalGroupMembership john.doe -Recursive

The -Recursive switch retrieves all nested group memberships regardless of depth.

Example 3: Get group memberships for all computers under an Organizational Unit

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

You can pipe strings containing a principal identity or ADObject objects to this cmdlet.

Example 4: Find circular nested groups

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

Example 5: Get group memberships for a user in a different Domain

PS> Get-ADTreePrincipalGroupMembership john.doe -Server otherDomain.com

Example 6: Display hierarchy even for previously processed groups

PS> Get-ADTreePrincipalGroupMembership john.doe -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 become the keys)
PS> $tree = Get-ADTreePrincipalGroupMembership john.doe -Properties PasswordLastSet, Department, City, nTSecurityDescriptor

# Show Department for the principal (if it's a user or has that property)
PS> $tree | Select-Object *, @{Name='Department'; Expression={ $_.AdditionalProperties['Department'] }}

# Or get everything
PS> $tree = Get-ADTreePrincipalGroupMembership john.doe -Properties *
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-ADTreePrincipalGroupMembership 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

-Identity

Specifies the Active Directory principal 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 principal identity (DistinguishedName, GUID, SID, sAMAccountName, or UserPrincipalName) to this cmdlet.

Microsoft.ActiveDirectory.Management.ADObject

ADObject objects are also accepted (typically piped from Get-ADUser, Get-ADComputer, Get-ADGroup, etc.).

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

treeprincipalmembership 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