PowerShell use of PrincipalContext.ValidateCredentials

Test-AdPassword.ps1

<#To do
    -Test local machine
    -Test remote domains
    -Explore AADJ experience
#>
function Test-Credential {
    <#
        .SYNOPSIS
            This function validates the credentials of a PSCredential (Get-Credential) object against the local machine or Active Directory.
            Active Directory users are first queried to add support for UPNs. Unfortunately this approach ignores the netbios name of the 
            PSCredential object. This means fakedomain\user1 will be evaluated as user1.

            Version: 25Jan2022
            Author: Mike Crowley
            
        .PARAMETER PSCredential
            Specifies that the user account is defined in a domain.

        .PARAMETER LocalUser
            Specifies that the user account is local to the machine, otherwise domain is assumed.
            
        .PARAMETER -DomainFQDN
            Specify the domain context. Otherwise the user's domain is assumed.

        .EXAMPLE
            #This example validates credentials for a local user
            $MyCred = Get-Credential
            Test-Credential -Verbose -PSCredential $MyCred -LocalUser $true

        .EXAMPLE
            #this example validates credentials for a domain user
            $MyCred = Get-Credential
            Test-Credential -Verbose -PSCredential $MyCred        

        .OUTPUTS
            Boolean

        .NOTES
            A fusion of the below topics:

            https://stackoverflow.com/questions/290548/validate-a-username-and-password-against-active-directory/499716
            https://community.idera.com/database-tools/powershell/powertips/b/tips/posts/validating-user-account-passwords-part-1
    #>

    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [PSCredential]
        $PSCredential,

        [Parameter()]
        [Boolean]
        $LocalUser,
        
        [Parameter()]
        [String]
        $DomainFQDN = $env:USERDNSDOMAIN
    )
    
    Add-Type -AssemblyName System.DirectoryServices.AccountManagement

    $ResolveUser = $PSCredential.GetNetworkCredential().domain.Length -lt 1
    
    If ($LocalUser) {
        $context          = [DirectoryServices.AccountManagement.ContextType]::Machine
        $PrincipalContext = [DirectoryServices.AccountManagement.PrincipalContext]::new($context, $env:COMPUTERNAME)
    }    
    else {        
        $Context            = [DirectoryServices.AccountManagement.ContextType]::Domain       
        $PrincipalContext   = [DirectoryServices.AccountManagement.PrincipalContext]::new($context, $DomainFQDN)
        $PasswordToValidate = $PSCredential.GetNetworkCredential().Password
        
        if ($ResolveUser) {
            Write-verbose "Searching AD. Please wait...`n"            
            # FindByIdentity seems to ignore the netbios domain part. This means fakedomain\user1 will be evaluated as user1. 
            $ADUser = [DirectoryServices.AccountManagement.UserPrincipal]::FindByIdentity($PrincipalContext , $PSCredential.UserName)
            $UserToValidate = $ADUser.SamAccountName
        }
        else {
            $UserToValidate = $PSCredential.GetNetworkCredential().UserName
        }
        
    }
    #Conduct credential test  
    Write-verbose "Testing credentials. Please wait...`n"
        
    $result = $PrincipalContext.ValidateCredentials($UserToValidate, $PasswordToValidate)

    #Guarantees an boolean output (vs null due to errors)
    return $result -eq $true
}



<# examples: 
    $MyCred = Get-Credential
    Test-Credential -Verbose -PSCredential $MyCred 


    $Cred1 = Get-Credential -Message "Enter Password" -UserName mike.crowley
    $Cred2 = Get-Credential -Message "Enter Password" -UserName example\mike.crorwley
    $Cred3 = Get-Credential -Message "Enter Password" -UserName mike.crowley@example.com

    Test-Credential -Verbose -PSCredential $Cred1
    Test-Credential -Verbose -PSCredential $Cred2
    Test-Credential -Verbose -PSCredential $Cred3
#>