Private/Select-ADObject.ps1
|
function Select-ADObject { <# .SYNOPSIS Displays an interactive GUI dialog to select an Active Directory object from the forest hierarchy. .DESCRIPTION Select-ADObject provides a graphical user interface (GUI) for browsing and selecting Active Directory objects such as Organizational Units (OUs), users, groups, and computers. The function displays a tree view of the forest structure with custom icons for different object types. It supports browsing across multiple domains and optionally highlights Tier 0 (high-security) objects. .COMPONENT Category: Sub Function .PARAMETER Title This text displayed in the dialog window title. Default is "Select AD Object". .PARAMETER LocalDomainOnly If specified, only the current domain and its contents are displayed. By default, all domains in the forest are shown. .PARAMETER DomainSelectionOnly If specified, only domain objects can be selected. The tree view is not expanded to show child objects. .PARAMETER OnlyUserSelectionPossible Includes users in the tree and allows only user objects to be selected. Takes precedence over DomainSelectionOnly when both switches are specified. .PARAMETER AddOU Enables a context menu for creating an organizational unit under a selected domain, OU, or container. .PARAMETER IncludeLinkedGPOs Displays GPOs linked to each domain, OU, or container as selectable child entries. .PARAMETER IncludeUsers If specified, user objects are included in the browsable tree view. .PARAMETER IncludeGroups If specified, group objects are included in the browsable tree view. .PARAMETER IncludeComputers If specified, computer objects are included in the browsable tree view. .PARAMETER MarkTier0 If specified, Tier 0 (high-security) objects are marked with a red overlay on their icons. This helps identify highly sensitive AD objects. .PARAMETER Tier0Regex A regular expression pattern used to identify Tier 0 objects. Default pattern matches: - CN=Administrator - OU=Domain Controllers - OU=Tier 0 (case-insensitive) - OU=T0 (case-insensitive) .OUTPUTS System.String Returns the distinguished name (DN) of the selected Active Directory object, or $null if the user cancels the dialog. .EXAMPLE PS> Select-ADObject -Title "Select Target OU" Description: Displays the AD selection dialog with a custom title title. Only OUs and containers are available for selection. .EXAMPLE PS> Select-ADObject -LocalDomainOnly -IncludeUsers -IncludeGroups Description: Shows only the current domain's contents, allowing selection of users and groups in addition to OUs. .EXAMPLE PS> Select-ADObject -DomainSelectionOnly Description: Restricts the selection to domain objects only. .EXAMPLE PS> Select-ADObject -MarkTier0 -IncludeUsers -Title "Select Tier 0 Target" Description: Displays all users and OUs, highlighting Tier 0 objects with a red indicator. .NOTES - Author: as2go@mrhozi.com - Version: 1.0 - Last Update: 2026-02-22 - This is a private function and requires a graphical environment (Windows Forms). - The function uses Active Directory modules to query the forest structure. - All logging is handled through Write-Log. .FUNCTIONALITY Browses AD objects in a graphical tree, with optional user-only selection, OU creation, and Tier 0 marking. #> [CmdletBinding()] param( [string]$Title = "Select AD Object", [switch]$LocalDomainOnly, [switch]$DomainSelectionOnly, [switch]$AddOU, [switch]$IncludeLinkedGPOs, [switch]$IncludeUsers, [switch]$IncludeGroups, [switch]$IncludeComputers, [switch]$IncludeGPOs, [switch]$MarkTier0, [Switch]$ShowAdvanced, [string]$Tier0Regex = '(?i)(^CN=Administrator,|^OU=Domain Controllers,|^OU=Tier\s*0|^OU=T0)', [switch]$OnlyUserSelectionPossible ) If ($Script:NotStandAlone) { $Info = Measure-FunctionRuntime -Begin } # ========================= # Assemblies # ========================= Add-Type -AssemblyName System.Windows.Forms Add-Type -AssemblyName System.Drawing Add-Type -AssemblyName System.DirectoryServices [System.Windows.Forms.Application]::EnableVisualStyles() # ========================= # Modern Icon Creation # ========================= <# .SYNOPSIS Creates a rounded-rectangle graphics path. .FUNCTIONALITY Builds the rounded paths used to draw the object-selection icons. #> function New-RoundedRectPath($X, $Y, $W, $H, $R) { $path = New-Object System.Drawing.Drawing2D.GraphicsPath $path.AddArc($X, $Y, $R, $R, 180, 90) $path.AddArc($X + $W - $R, $Y, $R, $R, 270, 90) $path.AddArc($X + $W - $R, $Y + $H - $R, $R, $R, 0, 90) $path.AddArc($X, $Y + $H - $R, $R, $R, 90, 90) $path.CloseFigure() $path } <# .SYNOPSIS Creates an icon bitmap for a directory object type. .FUNCTIONALITY Draws a 16-by-16 bitmap for the requested forest or Active Directory object type. #> function New-IconBitmap($Kind) { $bmp = New-Object System.Drawing.Bitmap 16, 16 $g = [System.Drawing.Graphics]::FromImage($bmp) $g.SmoothingMode = 'AntiAlias' $g.Clear([System.Drawing.Color]::Transparent) $stroke = New-Object System.Drawing.Pen([System.Drawing.Color]::FromArgb(60, 60, 60), 1) $fill = New-Object System.Drawing.SolidBrush([System.Drawing.Color]::FromArgb(220, 226, 232)) switch ($Kind) { 'Forest' { # Top node (Forest root) $g.FillEllipse($fill, 6, 2, 4, 4) $g.DrawEllipse($stroke, 6, 2, 4, 4) # Left child (Domain) $g.FillEllipse($fill, 3, 8, 4, 4) $g.DrawEllipse($stroke, 3, 8, 4, 4) # Right child (Domain) $g.FillEllipse($fill, 9, 8, 4, 4) $g.DrawEllipse($stroke, 9, 8, 4, 4) # Connection lines $g.DrawLine($stroke, 8, 6, 5, 8) $g.DrawLine($stroke, 8, 6, 11, 8) } 'Domain' { $points = [System.Drawing.Point[]]@( (New-Object System.Drawing.Point 8, 3), (New-Object System.Drawing.Point 13, 12), (New-Object System.Drawing.Point 3, 12) ) $g.FillPolygon($fill, $points) $g.DrawPolygon($stroke, $points) $g.DrawLine($stroke, 5, 9, 11, 9) } 'OU' { $p = New-RoundedRectPath 2 5 12 8 3 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) } 'Container' { $p = New-RoundedRectPath 3 4 10 10 3 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) $g.DrawLine($stroke, 4, 8, 12, 8) } 'User' { $g.FillEllipse($fill, 5, 3, 6, 6) $g.DrawEllipse($stroke, 5, 3, 6, 6) $p = New-RoundedRectPath 3 9 10 5 3 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) } 'Computer' { $p = New-RoundedRectPath 2 3 12 8 2 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) $g.DrawLine($stroke, 6, 12, 10, 12) $g.DrawLine($stroke, 8, 11, 8, 14) } 'Group' { $g.FillEllipse($fill, 4, 4, 4, 4) $g.DrawEllipse($stroke, 4, 4, 4, 4) $g.FillEllipse($fill, 8, 4, 4, 4) $g.DrawEllipse($stroke, 8, 4, 4, 4) $p = New-RoundedRectPath 4 9 8 4 3 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) } 'GPO' { # Center gear $g.FillEllipse($fill, 6, 6, 4, 4) $g.DrawEllipse($stroke, 6, 6, 4, 4) $g.FillEllipse([System.Drawing.Brushes]::White, 7, 7, 2, 2) $g.DrawEllipse($stroke, 7, 7, 2, 2) # Top tooth $p = New-RoundedRectPath 7 1 2 3 1 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) # Right tooth $p = New-RoundedRectPath 12 7 3 2 1 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) # Bottom tooth $p = New-RoundedRectPath 7 12 2 3 1 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) # Left tooth $p = New-RoundedRectPath 1 7 3 2 1 $g.FillPath($fill, $p) $g.DrawPath($stroke, $p) } } $g.Dispose() $bmp } <# .SYNOPSIS Marks an icon as belonging to Tier 0. .FUNCTIONALITY Adds a red overlay to the supplied bitmap. #> function Add-TierOverlay($bmp) { $clone = $bmp.Clone() $g = [System.Drawing.Graphics]::FromImage($clone) $g.FillEllipse([System.Drawing.Brushes]::Red, 10, 10, 5, 5) $g.Dispose() $clone } # ========================= # ImageList # ========================= $imageList = New-Object System.Windows.Forms.ImageList $imageList.ImageSize = '16,16' $imageList.Images.Add("Forest", (New-IconBitmap Forest)) | Out-Null $imageList.Images.Add("Domain", (New-IconBitmap Domain)) | Out-Null $imageList.Images.Add("OU", (New-IconBitmap OU)) | Out-Null $imageList.Images.Add("Container", (New-IconBitmap Container)) | Out-Null $imageList.Images.Add("User", (New-IconBitmap User)) | Out-Null $imageList.Images.Add("Computer", (New-IconBitmap Computer)) | Out-Null $imageList.Images.Add("Group", (New-IconBitmap Group)) | Out-Null $imageList.Images.Add("GPO", (New-IconBitmap GPO)) | Out-Null if ($MarkTier0) { foreach ($k in @("User", "OU", "Container", "Computer", "Group", "GPO")) { $imageList.Images.Add("${k}_T0", (Add-TierOverlay $imageList.Images[$k])) | Out-Null } } # ========================= # Helpers # ========================= <# .SYNOPSIS Converts a DNS domain name to a distinguished name. .FUNCTIONALITY Converts each domain component into a DC element. #> function Convert-DomainToDN($d) { 'DC=' + ($d -replace '\.', ',DC=') } <# .SYNOPSIS Returns the domain names in the current forest. .FUNCTIONALITY Reads and returns every domain name from the current Active Directory forest. #> function Get-ForestDomains { ([System.DirectoryServices.ActiveDirectory.Forest]::GetCurrentForest()).Domains | Select-Object -ExpandProperty Name } <# .SYNOPSIS Loads child objects for a node in the selection tree. .FUNCTIONALITY Queries LDAP for matching OUs, containers, and enabled object types on demand. #> function Get-ChildNodes($node) { if ($DomainSelectionOnly -and -not $OnlyUserSelectionPossible) { return } if ($node.Nodes.Count -eq 1 -and $node.Nodes[0].Text -eq 'dummy') { $node.Nodes.Clear() $root = [ADSI]"LDAP://$($node.Name)" $searcher = New-Object System.DirectoryServices.DirectorySearcher($root) $searcher.SearchScope = 'OneLevel' $filters = @( "(objectClass=organizationalUnit)", "(objectClass=container)" "(objectClass=builtinDomain)" ) if ($OnlyUserSelectionPossible) { $filters += "(&(objectCategory=person)(objectClass=user))" } elseif ($IncludeUsers) { $filters += "(objectCategory=user)" } if ($IncludeGroups) { $filters += "(objectCategory=group)" } if ($IncludeComputers) { $filters += "(objectCategory=computer)" } if ($IncludeGPOs) { $filters += "(objectCategory=groupPolicyContainer)" } $orFilter = "(|" + ($filters -join "") + ")" if (-not $ShowAdvanced) { $searcher.Filter = "(& $orFilter (!(showInAdvancedViewOnly=TRUE)))" } else { $searcher.Filter = $orFilter } write-verbose $orFilter $null = $searcher.PropertiesToLoad.AddRange(@("name", "distinguishedName", "objectClass")) foreach ($res in $searcher.FindAll()) { $dn = $res.Properties.distinguishedname[0] $name = $res.Properties.name[0] $cls = $res.Properties.objectclass[-1] # change icon here #$iconKey = if ($cls -eq "organizationalUnit") { "OU" } else { "User" } $iconKey = switch ($cls) { 'organizationalUnit' { 'OU' } 'container' { 'Container' } 'user' { 'User' } 'group' { 'Group' } 'computer' { 'Computer' } 'groupPolicyContainer' { 'GPO' } default { 'Container' } } if ($MarkTier0 -and $dn -match $Tier0Regex -and $imageList.Images.ContainsKey("${iconKey}_T0")) { $iconKey = "${iconKey}_T0" } $child = New-Object System.Windows.Forms.TreeNode $child.Text = $name $child.Name = $dn $child.Tag = [PSCustomObject]@{ Domain = $node.Tag.Domain; ObjectClass = $cls } $child.ImageKey = $iconKey $child.SelectedImageKey = $iconKey $child.Nodes.Add("dummy") | Out-Null $node.Nodes.Add($child) | Out-Null } if ($IncludeLinkedGPOs -and $root.Properties['gPLink'].Count -gt 0) { $gpoLinks = [regex]::Matches( [string]$root.Properties['gPLink'][0], '\[LDAP://(?<dn>[^;]+);\d+\]' ) $gpoIndex = 0 foreach ($gpoLink in $gpoLinks) { $gpoDn = $gpoLink.Groups['dn'].Value $gpoRoot = [ADSI]"LDAP://$gpoDn" $gpoSearcher = New-Object System.DirectoryServices.DirectorySearcher($gpoRoot) $gpoSearcher.SearchScope = 'Base' $gpoSearcher.Filter = '(objectClass=groupPolicyContainer)' $null = $gpoSearcher.PropertiesToLoad.Add('displayName') $gpoResult = $gpoSearcher.FindOne() if (-not $gpoResult) { continue } $gpoDisplayName = [string]$gpoResult.Properties['displayname'][0] if ([string]::IsNullOrWhiteSpace($gpoDisplayName)) { $gpoDisplayName = $gpoDn } $gpoNode = New-Object System.Windows.Forms.TreeNode $gpoNode.Text = $gpoDisplayName $gpoNode.Name = $gpoDn $gpoNode.Tag = [PSCustomObject]@{ Domain = $node.Tag.Domain; ObjectClass = 'groupPolicyContainer' } $gpoNode.ImageKey = 'GPO' $gpoNode.SelectedImageKey = 'GPO' $node.Nodes.Insert($gpoIndex, $gpoNode) $gpoIndex++ } } } } <# .SYNOPSIS Prompts for a new organizational unit name. .FUNCTIONALITY Shows a small dialog and returns the entered OU name when confirmed. #> function Show-OUNamePrompt { $dialog = New-Object System.Windows.Forms.Form $dialog.Text = "New Organizational Unit" $dialog.Size = '360,140' $dialog.StartPosition = 'CenterParent' $dialog.FormBorderStyle = 'FixedDialog' $dialog.MaximizeBox = $false $dialog.MinimizeBox = $false $label = New-Object System.Windows.Forms.Label $label.Text = "Organizational unit name:" $label.Location = '12,12' $label.Size = '320,20' $nameTextBox = New-Object System.Windows.Forms.TextBox $nameTextBox.Location = '12,36' $nameTextBox.Size = '320,22' $okButton = New-Object System.Windows.Forms.Button $okButton.Text = "Create" $okButton.DialogResult = [System.Windows.Forms.DialogResult]::OK $okButton.Location = '172,68' $okButton.Size = '75,26' $cancelButton = New-Object System.Windows.Forms.Button $cancelButton.Text = "Cancel" $cancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel $cancelButton.Location = '257,68' $cancelButton.Size = '75,26' $dialog.AcceptButton = $okButton $dialog.CancelButton = $cancelButton $dialog.Controls.AddRange(@($label, $nameTextBox, $okButton, $cancelButton)) if ($dialog.ShowDialog($form) -eq [System.Windows.Forms.DialogResult]::OK) { return $nameTextBox.Text.Trim() } } # ========================= # FORM # ========================= $form = New-Object System.Windows.Forms.Form $form.Text = $Title $form.Size = '520,700' $form.StartPosition = 'CenterScreen' $form.FormBorderStyle = 'FixedDialog' $form.MaximizeBox = $false $form.MinimizeBox = $false $form.Padding = '10,10,10,10' $font = New-Object System.Drawing.Font("Segoe UI", 9) $tree = New-Object System.Windows.Forms.TreeView $tree.Location = '10,10' $tree.Size = '480,560' $tree.Font = $font $tree.ImageList = $imageList $statusLabel = New-Object System.Windows.Forms.Label $statusLabel.Location = '10,580' $statusLabel.Size = '480,20' $statusLabel.Text = "Selected: none" $statusLabel.Font = $font $btnCancel = New-Object System.Windows.Forms.Button $btnCancel.Text = "Cancel" $btnCancel.Location = '310,610' $btnCancel.Size = '80,28' $btnCancel.Font = $font $btnOK = New-Object System.Windows.Forms.Button $btnOK.Text = "OK" $btnOK.Location = '410,610' $btnOK.Size = '80,28' $btnOK.Font = $font $btnOK.Enabled = $false $form.AcceptButton = $btnOK $form.CancelButton = $btnCancel # ========================= # Build Forest # ========================= $forestName = ([System.DirectoryServices.ActiveDirectory.Forest]::GetCurrentForest()).Name $forestNode = New-Object System.Windows.Forms.TreeNode $forestNode.Text = $forestName $forestNode.ImageKey = "Forest" $forestNode.SelectedImageKey = "Forest" $tree.Nodes.Add($forestNode) | Out-Null $domains = Get-ForestDomains $currentDomain = ([System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain()).Name foreach ($d in $domains) { if ($LocalDomainOnly -and $d -ne $currentDomain) { continue } $dn = Convert-DomainToDN $d $domainNode = New-Object System.Windows.Forms.TreeNode $domainNode.Text = $d $domainNode.Name = $dn $domainNode.Tag = [PSCustomObject]@{ Domain = $d; ObjectClass = 'domain' } $domainNode.ImageKey = "Domain" $domainNode.SelectedImageKey = "Domain" $domainNode.Nodes.Add("dummy") | Out-Null $forestNode.Nodes.Add($domainNode) | Out-Null } $forestNode.Expand() # ========================= # Events # ========================= $tree.add_BeforeExpand({ Get-ChildNodes $_.Node }) if ($AddOU) { $contextMenu = New-Object System.Windows.Forms.ContextMenuStrip $newMenuItem = New-Object System.Windows.Forms.ToolStripMenuItem("New") $addOuMenuItem = New-Object System.Windows.Forms.ToolStripMenuItem("Organizational Unit") $newMenuItem.DropDownItems.Add($addOuMenuItem) | Out-Null $contextMenu.Items.Add($newMenuItem) | Out-Null $tree.ContextMenuStrip = $contextMenu $tree.add_NodeMouseClick({ if ($_.Button -eq [System.Windows.Forms.MouseButtons]::Right) { $tree.SelectedNode = $_.Node } }) $addOuMenuItem.add_Click({ $parentNode = $tree.SelectedNode if (-not $parentNode -or -not $parentNode.Tag -or $parentNode.Tag.ObjectClass -notin @('domain', 'organizationalUnit', 'container', 'builtinDomain')) { return } $ouName = Show-OUNamePrompt if ([string]::IsNullOrWhiteSpace($ouName)) { return } try { $createdOU = New-ADOrganizationalUnit -Name $ouName -Path $parentNode.Name -Server $parentNode.Tag.Domain -PassThru -ErrorAction Stop Write-Log -Message "Created organizational unit '$($createdOU.DistinguishedName)'" # Refresh the parent's child nodes so the new OU is shown immediately $tree.BeginUpdate() try { $parentNode.Nodes.Clear() $parentNode.Nodes.Add("dummy") | Out-Null Get-ChildNodes $parentNode $parentNode.Expand() $newNode = $parentNode.Nodes | Where-Object { $_.Name -eq $createdOU.DistinguishedName } | Select-Object -First 1 if ($newNode) { $newNode.EnsureVisible() $tree.SelectedNode = $newNode } } finally { $tree.EndUpdate() } } catch { Write-Log -Message "Failed to create organizational unit '$ouName' under '$($parentNode.Name)': $_" [void][System.Windows.Forms.MessageBox]::Show($form, $_.Exception.Message, "OU creation failed", [System.Windows.Forms.MessageBoxButtons]::OK, [System.Windows.Forms.MessageBoxIcon]::Error) } }) } $tree.add_AfterSelect({ $node = $_.Node $statusLabel.Text = "Selected: $($node.Text)" if ($OnlyUserSelectionPossible) { $btnOK.Enabled = ($node.Tag -and $node.Tag.ObjectClass -eq 'user') return } if ($DomainSelectionOnly) { $btnOK.Enabled = ($node.Parent -and -not $node.Parent.Parent) return } if ($AllowDomainSwitch) { $btnOK.Enabled = [bool]($node.Parent) } else { $btnOK.Enabled = [bool]($node.Parent -and $node.Parent.Parent) } }) $btnOK.add_Click({ $form.Tag = $tree.SelectedNode.Name $form.Close() }) $btnCancel.add_Click({ $form.Tag = $null $form.Close() }) $form.Controls.AddRange(@($tree, $statusLabel, $btnCancel, $btnOK)) $null = $form.ShowDialog() If ($Script:NotStandAlone) { Write-Log -Message " >> AD Object selected: $($form.Tag)" Measure-FunctionRuntime -End -Details $Info } else { Write-Host " >> AD Object selected: $($form.Tag)" } return $form.Tag } |