CablersPowershellServers

1.0.2

src/Public/Set-ADUserPassword.ps1

<#
 
.SYNOPSIS
 
    Set the password for an Active Directory user account.
 
.DESCRIPTION
 
    Set the password for an Active Directory user account.
    Can set the password using a SecureString or a plain text string.
    If a plain text string is used, it will be converted to a SecureString before setting the password.
    If the password is blank, the script will use the DSQUERY and DSMOD command to reset the password instead of Set-ADAccountPassword.
 
    This script requires the Active Directory module to be installed.
 
.PARAMETER Username
 
    The username of the user account to set the password for.
 
.PARAMETER Password
 
    The password to set for the user account as a string. This parameter is a security risk, but is easier to use.
 
.PARAMETER SecureStringPassword
 
    The password to set for the user account as a SecureString.
 
.PARAMETER DoNotRequireChangeOnLogin
 
    If this switch is used, the user will not be required to change their password on next login.
 
.EXAMPLE
 
    Set-ADUserPassword -Username "TestUser" -Password "Password123"
 
    This example sets the password for the user account "TestUser" to "Password123".
 
.EXAMPLE
 
    Set-ADUserPassword -Username "TestUser" -SecureStringPassword (ConvertTo-SecureString -String "Password123" -AsPlainText -Force)
 
    This example sets the password for the user account "TestUser" to "Password123".
 
.EXAMPLE
 
    Set-ADUserPassword -Username "TestUser" -Password "Password123" -DoNotRequireChangeOnLogin
 
    This example sets the password for the user account "TestUser" to "Password123" and does not require the user to change their password on next login.
 
#>
function Set-ADUserPassword {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [ValidateNotNullOrEmpty()]
        [string[]]$Username,

        [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "String")]
        [string]$Password, # Security risk, but necessary for ease of use

        [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "SecureString")]
        [ValidateNotNullOrEmpty()]
        [SecureString]$SecureStringPassword,

        [Switch]$DoNotRequireChangeOnLogin
    )

    begin {

        If ($ParameterSetName -eq "String") {
            $Password = $Password.Trim()
            $SecureStringPassword = ConvertTo-SecureString -String $Password -AsPlainText -Force
        }

    }

    process {

        Foreach ($User in $Username) {
            Try {
                If (Get-ADUser -Filter { SamAccountName -eq $User }) {
                    Write-Verbose "User $User exists."
                }
                else {
                    Write-Error "User $User does not exist."
                    Continue
                }
                #If we are using a blank password, we need to use the DSQUERY and DSMOD command to reset the password instead of Set-ADAccountPassword
                If ($ParameterSetName -eq "String" -and (($Password.Length -eq 0) -or ($Null -eq $Password))) {
                    DSQUERY user -name $Username | DSMOD user -pwd $password -mustchpwd yes
                }
                else {
                    Set-ADAccountPassword -Identity $User -Password $SecureStringPassword -Reset
                    Write-Verbose "Successfully set password for user $User."
                }

                If ($DoNotRequireChangeOnLogin) {
                    Set-ADUser -Identity $User -ChangePasswordAtLogon $false
                }
            }
            Catch {
                Write-Error "An error occurred while resetting the password for user $User. $_"
                Continue
            }
        }
    }

    end {

    }
}