Public/Import-ADPrivilegedGroupDirectMember.ps1

<#
.SYNOPSIS
Restores missing direct memberships of privileged Active Directory groups from JSON.

.DESCRIPTION
Reads a backup created by Export-ADPrivilegedGroupDirectMember. Validates the recorded
forest, domain SIDs, and group records before adding members. Resolves groups by SID
and skips groups recorded as missing in the backup.

Member objects must still exist at their original distinguished names. The import
preserves existing memberships. Providing a path bypasses the AS2Go configuration.

.PARAMETER Path
Specifies the JSON backup file. If omitted, offers the latest backup saved under
ADPrivilegedGroupDirectMember in AS2Go.json. Opens a file selection dialog if the
saved backup is unavailable or you decline to use it.

.PARAMETER Silent
Suppresses routine console output, diagnostic streams, and result objects.
Errors and confirmation or WhatIf messages remain visible.

.PARAMETER Preview
Displays the planned steps without opening the file picker, reading a backup, or querying Active Directory.

.EXAMPLE
Import-ADPrivilegedGroupDirectMember -Path 'C:\Temp\ADGroupMembers.json' -WhatIf

Validates the backup against Active Directory and shows which memberships would be added.

.EXAMPLE
Import-ADPrivilegedGroupDirectMember -Path 'C:\Temp\ADGroupMembers.json'

Prompts for confirmation before adding missing members to the original groups.

.EXAMPLE
Import-ADPrivilegedGroupDirectMember | where-object {$_.Status -ne 'AlreadyMember'} | Select-Object Status, Domain, Group, MemberDn | ft

Offers the saved backup or opens the file picker, then displays the import results in a table.

.OUTPUTS
System.Management.Automation.PSCustomObject
Returns one result per distinct member in each restored group. Status is AlreadyMember,
Skipped, Added, or Failed. A failed addition includes the error message.

.NOTES
Requires the ActiveDirectory PowerShell module for import. Failed additions are reported
as they occur. The function raises a terminating error after processing the remaining members.

.LINK
Export-ADPrivilegedGroupDirectMember

.COMPONENT
Category: Main Function

.FUNCTIONALITY
Restores missing direct memberships of privileged groups from a JSON backup in the original forest.
Preserves existing group memberships.
#>

function Import-ADPrivilegedGroupDirectMember {
    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
    param(
        [Parameter(Position = 0)]
        [string]$Path,
        [switch]$Silent,
        [switch]$Preview
    )

    if ($Preview) {
        Show-AS2GoPreview -FunctionName 'Import-ADPrivilegedGroupDirectMember'
        return
    }

    $info = Measure-FunctionRuntime -Begin

    try {
        $ErrorActionPreference = 'Stop'
        if ($Silent) {
            $WarningPreference = 'SilentlyContinue'
            $VerbosePreference = 'SilentlyContinue'
            $DebugPreference = 'SilentlyContinue'
            $InformationPreference = 'SilentlyContinue'
            $ProgressPreference = 'SilentlyContinue'
        }
        else {
            Write-AS2GoOutput -Type Header -Message 'Import Privileged Group Memberships'
            Write-AS2GoOutput -Type H1 -Message $((Get-Help (Get-FunctionName)).Functionality)
        }

        if (-not $Path) {
            $SavedPath = Get-ASConfig -Setting 'ADPrivilegedGroupDirectMember'
            if ($SavedPath -match '\.json$' -and (Test-Path -LiteralPath $SavedPath -PathType Leaf)) {
                $Title = 'Use the latest membership backup?'
                $Message = "The AS2Go configuration points to this backup:`n$SavedPath`n`nDo you want to use it?"
                $Answer = Show-DecisionPrompt -Title $Title -Message $Message

                if ($Answer -eq $Script:Yes) {
                    $Path = $SavedPath
                }
            }
        }

        if (-not $Path) {
            Add-Type -AssemblyName System.Windows.Forms

            $Dialog = New-Object -TypeName System.Windows.Forms.OpenFileDialog
            try {
                $Dialog.Title = 'Select a group membership backup'
                $Dialog.Filter = 'JSON files (*.json)|*.json'
                $Dialog.Multiselect = $false
                $Dialog.CheckFileExists = $true
                $Dialog.InitialDirectory = (Get-Location).Path

                $DialogResult = $Dialog.ShowDialog()
                if ($DialogResult -ne [System.Windows.Forms.DialogResult]::OK -or
                    [string]::IsNullOrWhiteSpace($Dialog.FileName)) {
                    if (-not $Silent) {
                        Write-AS2GoOutput -Type Info -Message 'Import canceled. No backup file was selected.'
                    }
                    return
                }

                $Path = $Dialog.FileName
            }
            finally {
                $Dialog.Dispose()
            }
        }

        if ($Path -notmatch '(?i)\.json$') {
            throw "The configured or selected path '$Path' is not a JSON backup file."
        }

        $Data = Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json
        if ($Data.SchemaVersion -ne 1 -or $Data.MembershipType -ne 'DirectMemberAttribute' -or
            -not $Data.Forest -or -not @($Data.Domains).Count) {
            throw 'Unsupported or incomplete group membership JSON.'
        }

        Import-Module -Name ActiveDirectory -Scope Local
        $Forest = Get-ADForest -Identity $Data.Forest
        $Targets = @(
            # Validate every domain and group record before making any changes.
            foreach ($DomainRecord in $Data.Domains) {
                if ($DomainRecord.Domain -notin $Forest.Domains) {
                    throw "Domain $($DomainRecord.Domain) is not in forest $($Forest.Name)."
                }
                $Domain = Get-ADDomain -Identity $DomainRecord.Domain -Server $DomainRecord.Domain
                if ($Domain.DomainSID.Value -ne $DomainRecord.DomainSid) {
                    throw "Domain SID mismatch for $($DomainRecord.Domain)."
                }
                $DomainController = Get-ADDomainController -Discover -DomainName $DomainRecord.Domain -Writable
                $Server = [string](@($DomainController.HostName)[0])
                if ([string]::IsNullOrWhiteSpace($Server)) {
                    throw "No domain controller hostname was returned for $($DomainRecord.Domain)."
                }
                foreach ($GroupRecord in $DomainRecord.Groups) {
                    $ParsedRid = [uint32]0
                    if (-not [uint32]::TryParse([string]$GroupRecord.Rid, [ref]$ParsedRid) -or
                        $ParsedRid -eq 0 -or $GroupRecord.Status -notin 'Exported', 'Missing') {
                        throw "Invalid group record in $($DomainRecord.Domain)."
                    }
                    $ExpectedSid = if ($GroupRecord.Rid -in 548, 549, 550, 551) {
                        "S-1-5-32-$($GroupRecord.Rid)"
                    }
                    else {
                        "$($Domain.DomainSID.Value)-$($GroupRecord.Rid)"
                    }
                    if ($GroupRecord.Sid -ne $ExpectedSid) {
                        throw "Unexpected group SID: $($GroupRecord.Sid)."
                    }
                    if ($GroupRecord.Status -eq 'Missing') {
                        continue
                    }
                    if ($null -eq $GroupRecord.Members -or $GroupRecord.Members -isnot [System.Array]) {
                        throw "Missing or invalid member array for $ExpectedSid."
                    }
                    foreach ($MemberDn in $GroupRecord.Members) {
                        if ($MemberDn -isnot [string] -or [string]::IsNullOrWhiteSpace($MemberDn)) {
                            throw "Invalid member DN for $ExpectedSid."
                        }
                    }
                    $Group = Get-ADGroup -Identity $ExpectedSid -Server $Server -Properties member
                    [pscustomobject]@{
                        Domain  = $DomainRecord.Domain
                        Server  = $Server
                        Group   = $Group
                        Members = $GroupRecord.Members
                    }
                }
            }
        )

        $FailureCount = 0
        foreach ($Target in $Targets) {
            $ExistingMembers = @($Target.Group.member)
            foreach ($MemberDn in ($Target.Members | Sort-Object -Unique)) {
                $Status = 'AlreadyMember'
                $ErrorMessage = $null
                if ($MemberDn -notin $ExistingMembers) {
                    $Status = 'Skipped'
                    if ($PSCmdlet.ShouldProcess("$($Target.Domain): $($Target.Group.Name)", "Add direct member $MemberDn")) {
                        try {
                            # Use a typed string array: AD attribute hashtables do not unwrap JSON PSObject values.
                            # Writing the DN directly preserves nested groups and foreign security principals.
                            $MemberValues = [string[]]@("$MemberDn")
                            Set-ADGroup -Identity $Target.Group.DistinguishedName -Server $Target.Server -Add @{ member = $MemberValues } -Confirm:$false
                            $ExistingMembers += $MemberDn
                            $Status = 'Added'
                        }
                        catch {
                            $Status = 'Failed'
                            $ErrorMessage = $_.Exception.Message
                            $FailureCount++
                            Write-Warning "Cannot add $MemberDn to $($Target.Group.Name): $ErrorMessage"
                        }
                    }
                }
                if (-not $Silent) {
                    [pscustomobject]@{
                        Domain   = $Target.Domain
                        Group    = $Target.Group.Name
                        GroupSid = $Target.Group.SID.Value
                        MemberDn = $MemberDn
                        Status   = $Status
                        Error    = $ErrorMessage
                    }
                }
            }
        }

        if ($FailureCount) {
            throw "Import completed with $FailureCount failed membership additions. Review the results."
        }
    }
    finally {
        Measure-FunctionRuntime -End -Details $info
    }
}