DSC_Computer.psm1

[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidGlobalVars', '', Scope = 'Function')]
param
(
)

$modulePath = Join-Path -Path (Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent) -ChildPath 'Modules'

# Import the ComputerManagementDsc Common Modules
Import-Module -Name (Join-Path -Path $modulePath `
        -ChildPath (Join-Path -Path 'ComputerManagementDsc.Common' `
            -ChildPath 'ComputerManagementDsc.Common.psm1'))

Import-Module -Name (Join-Path -Path $modulePath -ChildPath 'DscResource.Common')

# Import Localization Strings
$script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'

$FailToRenameAfterJoinDomainErrorId = 'FailToRenameAfterJoinDomain,Microsoft.PowerShell.Commands.AddComputerCommand'

<#
    .SYNOPSIS
        Gets the current state of the computer.

    .PARAMETER Name
        The desired computer name.

    .PARAMETER DomainName
        The name of the domain to join.

    .PARAMETER JoinOU
        The distinguished name of the organizational unit that the computer
        account will be created in.

    .PARAMETER Credential
        Credential to be used to join a domain.

    .PARAMETER UnjoinCredential
        Credential to be used to leave a domain.

    .PARAMETER WorkGroupName
        The name of the workgroup.

    .PARAMETER Description
        The value assigned here will be set as the local computer description.

    .PARAMETER Server
        The Active Directory Domain Controller to use to join the domain.

    .PARAMETER Options
        Specifies advanced options for the Add-Computer join operation.
#>
function Get-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateLength(1, 15)]
        [ValidateScript( { $_ -inotmatch '[\/\\:*?"<>|]' })]
        [System.String]
        $Name,

        [Parameter()]
        [System.String]
        $DomainName,

        [Parameter()]
        [System.String]
        $JoinOU,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $Credential,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $UnjoinCredential,

        [Parameter()]
        [System.String]
        $WorkGroupName,

        [Parameter()]
        [System.String]
        $Description,

        [Parameter()]
        [System.String]
        $Server,

        [Parameter()]
        [ValidateSet('AccountCreate', 'Win9XUpgrade', 'UnsecuredJoin', 'PasswordPass', 'JoinWithNewName', 'JoinReadOnly', 'InstallInvoke')]
        [System.String[]]
        $Options
    )

    Write-Verbose -Message ($script:localizedData.GettingComputerStateMessage -f $Name)

    $convertToCimCredential = New-CimInstance `
        -ClassName DSC_Credential `
        -Property @{
            Username = [System.String] $Credential.UserName
            Password = [System.String] $null
        } `
        -Namespace root/microsoft/windows/desiredstateconfiguration `
        -ClientOnly

    $convertToCimUnjoinCredential = New-CimInstance `
        -ClassName DSC_Credential `
        -Property @{
            Username = [System.String] $UnjoinCredential.UserName
            Password = [System.String] $null
        } `
        -Namespace root/microsoft/windows/desiredstateconfiguration `
        -ClientOnly

    $returnValue = @{
        Name             = $env:COMPUTERNAME
        DomainName       = Get-ComputerDomain
        JoinOU           = $JoinOU
        CurrentOU        = Get-ComputerOU
        Credential       = [ciminstance] $convertToCimCredential
        UnjoinCredential = [ciminstance] $convertToCimUnjoinCredential
        WorkGroupName    = (Get-CimInstance -Class 'Win32_ComputerSystem').Workgroup
        Description      = (Get-CimInstance -Class 'Win32_OperatingSystem').Description
        Server           = Get-LogonServer
    }

    return $returnValue
}

<#
    .SYNOPSIS
        Sets the current state of the computer.

    .PARAMETER Name
        The desired computer name.

    .PARAMETER DomainName
        The name of the domain to join.

    .PARAMETER JoinOU
        The distinguished name of the organizational unit that the computer
        account will be created in.

    .PARAMETER Credential
        Credential to be used to join a domain.

    .PARAMETER UnjoinCredential
        Credential to be used to leave a domain.

    .PARAMETER WorkGroupName
        The name of the workgroup.

    .PARAMETER Description
        The value assigned here will be set as the local computer description.

    .PARAMETER Server
        The Active Directory Domain Controller to use to join the domain.

    .PARAMETER Options
        Specifies advanced options for the Add-Computer join operation.
#>
function Set-TargetResource
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateLength(1, 15)]
        [ValidateScript( { $_ -inotmatch '[\/\\:*?"<>|]' })]
        [System.String]
        $Name,

        [Parameter()]
        [System.String]
        $DomainName,

        [Parameter()]
        [System.String]
        $JoinOU,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $Credential,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $UnjoinCredential,

        [Parameter()]
        [System.String]
        $WorkGroupName,

        [Parameter()]
        [System.String]
        $Description,

        [Parameter()]
        [System.String]
        $Server,

        [Parameter()]
        [ValidateSet('AccountCreate', 'Win9XUpgrade', 'UnsecuredJoin', 'PasswordPass', 'JoinWithNewName', 'JoinReadOnly', 'InstallInvoke')]
        [System.String[]]
        $Options
    )

    Write-Verbose -Message ($script:localizedData.SettingComputerStateMessage -f $Name)

    Assert-DomainOrWorkGroup -DomainName $DomainName -WorkGroupName $WorkGroupName

    if ($Name -eq 'localhost')
    {
        $Name = $env:COMPUTERNAME
    }

    if ($PSBoundParameters.ContainsKey('Description'))
    {
        Write-Verbose -Message ($script:localizedData.SettingComputerDescriptionMessage -f $Description)
        $win32OperatingSystemCimInstance = Get-CimInstance -ClassName Win32_OperatingSystem
        $win32OperatingSystemCimInstance.Description = $Description
        Set-CimInstance -InputObject $win32OperatingSystemCimInstance
    }

    if ($Credential)
    {
        if ($DomainName)
        {
            if ($DomainName -eq (Get-ComputerDomain))
            {
                # Rename the computer, but stay joined to the domain.
                Rename-Computer -NewName $Name -DomainCredential $Credential -Force
                Write-Verbose -Message ($script:localizedData.RenamedComputerMessage -f $Name)
            }
            else
            {
                $addComputerParameters = @{
                    DomainName = $DomainName
                    Credential = $Credential
                    Force      = $true
                }
                $rename = $false
                if ($Name -ne $env:COMPUTERNAME)
                {
                    $addComputerParameters.Add("NewName", $Name)
                    $rename = $true
                }

                if ($UnjoinCredential)
                {
                    $addComputerParameters.Add("UnjoinDomainCredential", $UnjoinCredential)
                }

                if ($JoinOU)
                {
                    $addComputerParameters.Add("OUPath", $JoinOU)
                }

                if ($Server)
                {
                    $addComputerParameters.Add("Server", $Server)
                }

                # Check for existing computer objecst using ADSI without ActiveDirectory module
                $computerObject = Get-ADSIComputer -Name $Name -DomainName $DomainName -Credential $Credential

                if ($computerObject)
                {
                    Delete-ADSIObject -Path $computerObject.Path -Credential $Credential
                    Write-Verbose -Message ($script:localizedData.DeletedExistingComputerObject -f $Name, $computerObject.Path)
                }

                if (-not [System.String]::IsNullOrEmpty($Options))
                {
                    <#
                        See https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/add-computer?view=powershell-5.1#parameters for available options and their description
                    #>
                    Assert-ResourceProperty @PSBoundParameters
                    $addComputerParameters.Add('Options', $Options)
                }

                # Rename the computer, and join it to the domain.
                try
                {
                    Add-Computer @addComputerParameters
                }
                catch [System.InvalidOperationException]
                {
                    <#
                        If the rename failed during the domain join, re-try the rename.
                        References to this issue:
                        https://social.technet.microsoft.com/Forums/windowsserver/en-US/81105b18-b1ff-4fcc-ae5c-2c1a7cf7bf3d/addcomputer-to-domain-with-new-name-returns-error
                        https://powershell.org/forums/topic/the-directory-service-is-busy/
                    #>
                    if ($_.FullyQualifiedErrorId -eq $failToRenameAfterJoinDomainErrorId)
                    {
                        Write-Verbose -Message $script:localizedData.FailToRenameAfterJoinDomainMessage
                        Rename-Computer -NewName $Name -DomainCredential $Credential
                    }
                    else
                    {
                        New-InvalidOperationException -Message $_.Exception.Message -ErrorRecord $_
                    }
                }
                catch
                {
                    throw $_
                }

                if ($rename)
                {
                    Write-Verbose -Message ($script:localizedData.RenamedComputerAndJoinedDomainMessage -f $Name, $DomainName)
                }
                else
                {
                    Write-Verbose -Message ($script:localizedData.JoinedDomainMessage -f $DomainName)
                }
            }
        }
        elseif ($WorkGroupName)
        {
            if ($WorkGroupName -eq (Get-CimInstance -Class 'Win32_ComputerSystem').Workgroup)
            {
                # Rename the computer, but stay in the same workgroup.
                Rename-Computer `
                    -NewName $Name

                Write-Verbose -Message ($script:localizedData.RenamedComputerMessage -f $Name)
            }
            else
            {
                if ($Name -ne $env:COMPUTERNAME)
                {
                    # Rename the computer, and join it to the workgroup.
                    Add-Computer `
                        -NewName $Name `
                        -Credential $Credential `
                        -WorkgroupName $WorkGroupName `
                        -Force

                    Write-Verbose -Message ($script:localizedData.RenamedComputerAndJoinedWorkgroupMessage -f $Name, $WorkGroupName)
                }
                else
                {
                    # Same computer name, and join it to the workgroup.
                    Add-Computer `
                        -WorkGroupName $WorkGroupName `
                        -Credential $Credential `
                        -Force

                    Write-Verbose -Message ($script:localizedData.JoinedWorkgroupMessage -f $WorkGroupName)
                }
            }
        }
        elseif ($Name -ne $env:COMPUTERNAME)
        {
            if (Get-ComputerDomain)
            {
                Rename-Computer `
                    -NewName $Name `
                    -DomainCredential $Credential `
                    -Force

                Write-Verbose -Message ($script:localizedData.RenamedComputerMessage -f $Name)
            }
            else
            {
                Rename-Computer `
                    -NewName $Name `
                    -Force

                Write-Verbose -Message ($script:localizedData.RenamedComputerMessage -f $Name)
            }
        }
    }
    else
    {
        if ($DomainName)
        {
            New-InvalidArgumentException `
                -Message ($script:localizedData.CredentialsNotSpecifiedError) `
                -ArgumentName 'Credentials'
        }

        if ($WorkGroupName)
        {
            if ($WorkGroupName -eq (Get-CimInstance -Class 'Win32_ComputerSystem').Workgroup)
            {
                # Same workgroup, new computer name
                Rename-Computer `
                    -NewName $Name `
                    -Force

                Write-Verbose -Message ($script:localizedData.RenamedComputerMessage -f $Name)
            }
            else
            {
                if ($name -ne $env:COMPUTERNAME)
                {
                    # New workgroup, new computer name
                    Add-Computer `
                        -WorkgroupName $WorkGroupName `
                        -NewName $Name

                    Write-Verbose -Message ($script:localizedData.RenamedComputerAndJoinedWorkgroupMessage -f $Name, $WorkGroupName)
                }
                else
                {
                    # New workgroup, same computer name
                    Add-Computer `
                        -WorkgroupName $WorkGroupName

                    Write-Verbose -Message ($script:localizedData.JoinedWorkgroupMessage -f $WorkGroupName)
                }
            }
        }
        else
        {
            if ($Name -ne $env:COMPUTERNAME)
            {
                Rename-Computer `
                    -NewName $Name

                Write-Verbose -Message ($script:localizedData.RenamedComputerMessage -f $Name)
            }
        }
    }

    $global:DSCMachineStatus = 1
}

<#
    .SYNOPSIS
        Tests the current state of the computer.

    .PARAMETER Name
        The desired computer name.

    .PARAMETER DomainName
        The name of the domain to join.

    .PARAMETER JoinOU
        The distinguished name of the organizational unit that the computer
        account will be created in.

    .PARAMETER Credential
        Credential to be used to join a domain.

    .PARAMETER UnjoinCredential
        Credential to be used to leave a domain.

    .PARAMETER WorkGroupName
        The name of the workgroup.

    .PARAMETER Description
        The value assigned here will be set as the local computer description.

    .PARAMETER Options
        Specifies advanced options for the Add-Computer join operation.
#>
function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateLength(1, 15)]
        [ValidateScript( { $_ -inotmatch '[\/\\:*?"<>|]' })]
        [System.String]
        $Name,

        [Parameter()]
        [System.String]
        $JoinOU,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $Credential,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $UnjoinCredential,

        [Parameter()]
        [System.String]
        $DomainName,

        [Parameter()]
        [System.String]
        $WorkGroupName,

        [Parameter()]
        [System.String]
        $Description,

        [Parameter()]
        [System.String]
        $Server,

        [Parameter()]
        [ValidateSet('AccountCreate', 'Win9XUpgrade', 'UnsecuredJoin', 'PasswordPass', 'JoinWithNewName', 'JoinReadOnly', 'InstallInvoke')]
        [System.String[]]
        $Options
    )

    Write-Verbose -Message ($script:localizedData.TestingComputerStateMessage -f $Name)

    if (($Name -ne 'localhost') -and ($Name -ne $env:COMPUTERNAME))
    {
        return $false
    }

    if ($PSBoundParameters.ContainsKey('Description'))
    {
        Write-Verbose -Message ($script:localizedData.CheckingComputerDescriptionMessage -f $Description)

        if ($Description -ne (Get-CimInstance -Class 'Win32_OperatingSystem').Description)
        {
            return $false
        }
    }

    Assert-DomainOrWorkGroup -DomainName $DomainName -WorkGroupName $WorkGroupName

    if ($DomainName)
    {
        if (-not ($Credential))
        {
            New-InvalidArgumentException `
                -Message ($script:localizedData.CredentialsNotSpecifiedError) `
                -ArgumentName 'Credentials'
        }

        try
        {
            Write-Verbose -Message ($script:localizedData.CheckingDomainMemberMessage -f $DomainName)

            if ($DomainName.Contains('.'))
            {
                $getComputerDomainParameters = @{
                    netbios = $false
                }
            }
            else
            {
                $getComputerDomainParameters = @{
                    netbios = $true
                }
            }

            return ($DomainName -eq (Get-ComputerDomain @getComputerDomainParameters))
        }
        catch
        {
            Write-Verbose -Message ($script:localizedData.CheckingNotDomainMemberMessage)

            return $false
        }
    }
    elseif ($WorkGroupName)
    {
        Write-Verbose -Message ($script:localizedData.CheckingWorkgroupMemberMessage -f $WorkGroupName)

        return ($WorkGroupName -eq (Get-CimInstance -Class 'Win32_ComputerSystem').Workgroup)
    }
    else
    {
        # No Domain or Workgroup specified and computer name is correct
        return $true
    }
}

<#
    .SYNOPSIS
        Throws an exception if both the domain name and workgroup
        name is set.

    .PARAMETER DomainName
        The name of the domain to join.

    .PARAMETER WorkGroupName
        The name of the workgroup.
#>
function Assert-DomainOrWorkGroup
{
    [CmdletBinding()]
    param
    (
        [Parameter()]
        [System.String]
        $DomainName,

        [Parameter()]
        [System.String]
        $WorkGroupName
    )

    if ($DomainName -and $WorkGroupName)
    {
        New-InvalidOperationException `
            -Message ($script:localizedData.DomainNameAndWorkgroupNameError)
    }
}

<#
    .SYNOPSIS
        Returns the domain the computer is joined to.

    .PARAMETER NetBios
        Specifies if the NetBIOS name is returned instead of
        the fully qualified domain name.
#>
function Get-ComputerDomain
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter()]
        [Switch]
        $NetBios
    )

    try
    {
        $domainInfo = Get-CimInstance -ClassName Win32_ComputerSystem
        if ($domainInfo.PartOfDomain -eq $true)
        {
            if ($NetBios)
            {
                $domainName = (Get-Item -Path Env:\USERDOMAIN).Value
            }
            else
            {
                $domainName = $domainInfo.Domain
            }
        }
        else
        {
            $domainName = ''
        }

        return $domainName
    }
    catch [System.Management.Automation.MethodInvocationException]
    {
        Write-Verbose -Message ($script:localizedData.ComputerNotInDomainMessage)
    }
}

<#
    .SYNOPSIS
        Gets the organisation unit in the domain that the
        computer account exists in.
#>
function Get-ComputerOU
{
    [CmdletBinding()]
    param
    (
    )

    $ou = $null

    if (Get-ComputerDomain)
    {
        $dn = $null
        $dn = ([adsisearcher]"(&(objectCategory=computer)(objectClass=computer)(cn=$env:COMPUTERNAME))").FindOne().Properties.distinguishedname
        $ou = $dn -replace '^(CN=.*?(?<=,))', ''
    }

    return $ou
}

<#
    .SYNOPSIS
        Returns the logon server.
#>
function Get-LogonServer
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param ()

    $logonserver = $env:LOGONSERVER -replace "\\", ""
    return $logonserver
}

<#
    .SYNOPSIS
        Returns an ADSI Computer Object.

    .PARAMETER Name
        Name of the computer to search for in the given domain.

    .PARAMETER Domain
        Domain to search.

    .PARAMETER Credential
        Credential to search domain with.
#>
function Get-ADSIComputer
{
    [CmdletBinding()]
    [OutputType([System.DirectoryServices.SearchResult])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateLength(1, 15)]
        [ValidateScript( { $_ -inotmatch '[\/\\:*?"<>|]' })]
        [System.String]
        $Name,

        [Parameter(Mandatory = $true)]
        [System.String]
        $DomainName,

        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $Credential
    )

    $searcher = New-Object -TypeName System.DirectoryServices.DirectorySearcher
    $searcher.Filter = "(&(objectCategory=computer)(objectClass=computer)(cn=$Name))"
    if ($DomainName -notlike "LDAP://*")
    {
        $DomainName = "LDAP://$DomainName"
    }

    $params = @{
        TypeName     = 'System.DirectoryServices.DirectoryEntry'
        ArgumentList = @(
            $DomainName,
            $Credential.UserName,
            $Credential.GetNetworkCredential().password
        )
        ErrorAction  = 'Stop'
    }
    $searchRoot = New-Object @params
    $searcher.SearchRoot = $searchRoot

    return $searcher.FindOne()
}

<#
    .SYNOPSIS
        Deletes an ADSI DirectoryEntry Object.

    .PARAMETER Path
        Path to Object to delete.

    .PARAMETER Credential
        Credential to authenticate to the domain.
#>
function Delete-ADSIObject
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateScript( { $_ -imatch "LDAP://*" })]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $Credential
    )

    $params = @{
        TypeName     = 'System.DirectoryServices.DirectoryEntry'
        ArgumentList = @(
            $DomainName,
            $Credential.UserName
            $Credential.GetNetworkCredential().password
        )
        ErrorAction  = 'Stop'
    }
    $adsiObj = New-Object @params

    $adsiObj.DeleteTree()
}

<#
    .SYNOPSIS
    This function validates the parameters passed. Called by Set-Resource.
        Will throw an error if any parameters are invalid.

    .PARAMETER Name
        The desired computer name.

    .PARAMETER DomainName
        The name of the domain to join.

    .PARAMETER JoinOU
        The distinguished name of the organizational unit that the computer
        account will be created in.

    .PARAMETER Credential
        Credential to be used to join a domain.

    .PARAMETER UnjoinCredential
        Credential to be used to leave a domain.

    .PARAMETER WorkGroupName
        The name of the workgroup.

    .PARAMETER Description
        The value assigned here will be set as the local computer description.

    .PARAMETER Options
        Specifies advanced options for the Add-Computer join operation.
#>
function Assert-ResourceProperty
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateLength(1, 15)]
        [ValidateScript( { $_ -inotmatch '[\/\\:*?"<>|]' })]
        [System.String]
        $Name,

        [Parameter()]
        [System.String]
        $DomainName,

        [Parameter()]
        [System.String]
        $JoinOU,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $Credential,

        [Parameter()]
        [System.Management.Automation.PSCredential]
        $UnjoinCredential,

        [Parameter()]
        [System.String]
        $WorkGroupName,

        [Parameter()]
        [System.String]
        $Description,

        [Parameter()]
        [System.String]
        $Server,

        [Parameter()]
        [ValidateSet('AccountCreate', 'Win9XUpgrade', 'UnsecuredJoin', 'PasswordPass', 'JoinWithNewName', 'JoinReadOnly', 'InstallInvoke')]
        [System.String[]]
        $Options
    )

    if ($options -contains 'PasswordPass' -and
        $options -notcontains 'UnsecuredJoin')
    {
        New-InvalidArgumentException `
            -Message $script:localizedData.InvalidOptionPasswordPassUnsecuredJoin `
            -ArgumentName 'PasswordPass'
    }

    if ($Options -contains 'PasswordPass' -and
        $options -contains 'UnsecuredJoin' -and
        -not [System.String]::IsNullOrEmpty($Credential.UserName))
    {

        New-InvalidArgumentException `
            -Message $script:localizedData.InvalidOptionCredentialUnsecuredJoinNullUsername `
            -ArgumentName 'Credential'
    }
}

Export-ModuleMember -Function *-TargetResource