sqmSQLTool › Commands › Get-sqmHpuAllowGroup

Get-sqmHpuAllowGroup Security

Resolves the HPU (High-Privilege User) allow group from Active Directory by matching the current machine domain against a configurable domain-to-group mapping. Returns the DistinguishedName of the matched group or $null.

Execution Flow

START Get-CimInstance Win32_ComputerSystem → .Domain (current machine domain) return $null Get-sqmConfig -Key 'HpuDomainGroupMap' → array of {DomainPattern, GroupNamePattern} Write-Warning + return $null foreach ($entry in $domainGroupMap) — first match wins if ($currentDomain -like $entry.DomainPattern) → $matchedEntry = $entry; break DomainPattern supports wildcards: 'your.domain', '*.your.domain', '*' (catch-all) Match found? Write-Warning + return $null ADSI [adsisearcher] search LDAP filter: (&(objectCategory=group)(sAMAccountName=*$GroupNamePattern)) PageSize=20; PropertiesToLoad: name, distinguishedname; FindOne() Group found? Write-Warning + return $null Return DistinguishedName [string] DONE

Synopsis

Reads the HpuDomainGroupMap configuration key — an ordered array of {DomainPattern, GroupNamePattern} objects — and matches the current machine's domain against each entry using PowerShell wildcard syntax. The first matching entry's GroupNamePattern is used as the sAMAccountName filter for an ADSI group search. Returns the group's DistinguishedName on success, or $null on any failure.

No dbatools required. Uses pure ADSI ([adsisearcher]). Domain patterns support wildcards: exact match ('corp.example.com'), subdomain wildcard ('*.example.com'), or universal catch-all ('*'). Pattern evaluation is ordered — the first match wins.

Configuration

# Configure domain-group mappings via Set-sqmConfig
Set-sqmConfig -HpuDomainGroupMap @(
    [PSCustomObject]@{ DomainPattern = 'corp.example.com'; GroupNamePattern = 'Fg_DC_AouAllowManageAuditSecLogSrvAll_Mod' },
    [PSCustomObject]@{ DomainPattern = '*.example.com';   GroupNamePattern = 'Rg_DC_AouAllowManageAuditSecLogSrvAll_Mod' },
    [PSCustomObject]@{ DomainPattern = '*';               GroupNamePattern = 'Rg_DC_AouAllowManageAuditSecLogSrvAll_Mod' }
)

Syntax

Get-sqmHpuAllowGroup
    [-EnableException]

Parameters

ParameterTypeDefaultDescription
-EnableExceptionSwitchfalseThrow terminating exceptions instead of returning $null and writing warnings.

Return Value

TypeDescription
[string]DistinguishedName of the matched AD group, e.g. CN=Rg_DC_AouAllowManageAuditSecLogSrvAll_Mod,OU=Groups,DC=corp,DC=example,DC=com.
$nullReturned when: domain cannot be determined; HpuDomainGroupMap is not configured; no pattern matches the current domain; group not found in AD.

Examples

# Resolve the HPU allow group for the current machine
Get-sqmHpuAllowGroup

# Throw on failure instead of returning $null
Get-sqmHpuAllowGroup -EnableException

# Use result as input to another function
$dn = Get-sqmHpuAllowGroup
Write-Host "HPU group DN: $dn"