SharedResources/Src/JoinADDomain/xActiveDirectory/DSCResources/MSFT_xADUser/MSFT_xADUser.psm1

[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingUserNameAndPassWordParams', '')]
param()

# Localized messages
data LocalizedData
{
    # culture="en-US"
    ConvertFrom-StringData @'
        RoleNotFoundError              = Please ensure that the PowerShell module for role '{0}' is installed.
        RetrievingADUserError          = Error looking up Active Directory user '{0}' ({0}@{1}).
        PasswordParameterConflictError = Parameter '{0}' cannot be set to '{1}' when the '{2}' parameter is specified.

        RetrievingADUser               = Retrieving Active Directory user '{0}' ({0}@{1}) ...
        CreatingADDomainConnection     = Creating connection to Active Directory domain '{0}' ...
        CheckingADUserPassword         = Checking Active Directory user '{0}' password ...
        ADUserIsPresent                = Active Directory user '{0}' ({0}@{1}) is present.
        ADUserNotPresent               = Active Directory user '{0}' ({0}@{1}) was NOT present.
        ADUserNotDesiredPropertyState  = User '{0}' property is NOT in the desired state. Expected '{1}', actual '{2}'.

        AddingADUser                   = Adding Active Directory user '{0}'.
        RemovingADUser                 = Removing Active Directory user '{0}'.
        UpdatingADUser                 = Updating Active Directory user '{0}'.
        SettingADUserPassword          = Setting Active Directory user password.
        UpdatingADUserProperty         = Updating user property '{0}' with/to '{1}'.
        RemovingADUserProperty         = Removing user property '{0}' with '{1}'.
        MovingADUser                   = Moving user from '{0}' to '{1}'.
        RenamingADUser                 = Renaming user from '{0}' to '{1}'.
'@
}

## Create a property map that maps the DSC resource parameters to the
## Active Directory user attributes.
$adPropertyMap = @(
    @{ Parameter = 'CommonName'; ADProperty = 'cn'; }
    @{ Parameter = 'UserPrincipalName'; }
    @{ Parameter = 'DisplayName'; }
    @{ Parameter = 'Path'; ADProperty = 'distinguishedName'; }
    @{ Parameter = 'GivenName'; }
    @{ Parameter = 'Initials'; }
    @{ Parameter = 'Surname'; ADProperty = 'sn'; }
    @{ Parameter = 'Description'; }
    @{ Parameter = 'StreetAddress'; }
    @{ Parameter = 'POBox'; }
    @{ Parameter = 'City'; ADProperty = 'l'; }
    @{ Parameter = 'State'; ADProperty = 'st'; }
    @{ Parameter = 'PostalCode'; }
    @{ Parameter = 'Country'; ADProperty = 'c'; }
    @{ Parameter = 'Department'; }
    @{ Parameter = 'Division'; }
    @{ Parameter = 'Company'; }
    @{ Parameter = 'Office'; ADProperty = 'physicalDeliveryOfficeName'; }
    @{ Parameter = 'JobTitle'; ADProperty = 'title'; }
    @{ Parameter = 'EmailAddress'; ADProperty = 'mail'; }
    @{ Parameter = 'EmployeeID'; }
    @{ Parameter = 'EmployeeNumber'; }
    @{ Parameter = 'HomeDirectory'; }
    @{ Parameter = 'HomeDrive'; }
    @{ Parameter = 'HomePage'; ADProperty = 'wWWHomePage'; }
    @{ Parameter = 'ProfilePath'; }
    @{ Parameter = 'LogonScript'; ADProperty = 'scriptPath'; }
    @{ Parameter = 'Notes'; ADProperty = 'info'; }
    @{ Parameter = 'OfficePhone'; ADProperty = 'telephoneNumber'; }
    @{ Parameter = 'MobilePhone'; ADProperty = 'mobile'; }
    @{ Parameter = 'Fax'; ADProperty = 'facsimileTelephoneNumber'; }
    @{ Parameter = 'Pager'; }
    @{ Parameter = 'IPPhone'; }
    @{ Parameter = 'HomePhone'; }
    @{ Parameter = 'Enabled'; }
    @{ Parameter = 'Manager'; }
    @{ Parameter = 'PasswordNeverExpires'; UseCmdletParameter = $true; }
    @{ Parameter = 'CannotChangePassword'; UseCmdletParameter = $true; }
)

function Get-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        ## Name of the domain where the user account is located (only used if password is managed)
        [Parameter(Mandatory)]
        [System.String] $DomainName,

        # Specifies the Security Account Manager (SAM) account name of the user (ldapDisplayName 'sAMAccountName')
        [Parameter(Mandatory)]
        [System.String] $UserName,

        ## Specifies a new password value for an account
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $Password,

        ## Specifies whether the user account is created or deleted
        [ValidateSet('Present', 'Absent')]
        [System.String] $Ensure = 'Present',

        ## Specifies the common nane assigned to the user account (ldapDisplayName 'cn')
        [ValidateNotNull()]
        [System.String] $CommonName = $UserName,

        ## Specifies the UPN assigned to the user account (ldapDisplayName 'userPrincipalName')
        [ValidateNotNull()]
        [System.String] $UserPrincipalName,

        ## Specifies the display name of the object (ldapDisplayName 'displayName')
        [ValidateNotNull()]
        [System.String] $DisplayName,

        ## Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created
        [ValidateNotNull()]
        [System.String] $Path,

        ## Specifies the user's given name (ldapDisplayName 'givenName')
        [ValidateNotNull()]
        [System.String] $GivenName,

        ## Specifies the initials that represent part of a user's name (ldapDisplayName 'initials')
        [ValidateNotNull()]
        [System.String] $Initials,

        ## Specifies the user's last name or surname (ldapDisplayName 'sn')
        [ValidateNotNull()]
        [System.String] $Surname,

        ## Specifies a description of the object (ldapDisplayName 'description')
        [ValidateNotNull()]
        [System.String] $Description,

        ## Specifies the user's street address (ldapDisplayName 'streetAddress')
        [ValidateNotNull()]
        [System.String] $StreetAddress,

        ## Specifies the user's post office box number (ldapDisplayName 'postOfficeBox')
        [ValidateNotNull()]
        [System.String] $POBox,

        ## Specifies the user's town or city (ldapDisplayName 'l')
        [ValidateNotNull()]
        [System.String] $City,

        ## Specifies the user's or Organizational Unit's state or province (ldapDisplayName 'st')
        [ValidateNotNull()]
        [System.String] $State,

        ## Specifies the user's postal code or zip code (ldapDisplayName 'postalCode')
        [ValidateNotNull()]
        [System.String] $PostalCode,

        ## Specifies the country or region code for the user's language of choice (ldapDisplayName 'c')
        [ValidateNotNull()]
        [System.String] $Country,

        ## Specifies the user's department (ldapDisplayName 'department')
        [ValidateNotNull()]
        [System.String] $Department,

        ## Specifies the user's division (ldapDisplayName 'division')
        [ValidateNotNull()]
        [System.String] $Division,

        ## Specifies the user's company (ldapDisplayName 'company')
        [ValidateNotNull()]
        [System.String] $Company,

        ## Specifies the location of the user's office or place of business (ldapDisplayName 'physicalDeliveryOfficeName')
        [ValidateNotNull()]
        [System.String] $Office,

        ## Specifies the user's title (ldapDisplayName 'title')
        [ValidateNotNull()]
        [System.String] $JobTitle,

        ## Specifies the user's e-mail address (ldapDisplayName 'mail')
        [ValidateNotNull()]
        [System.String] $EmailAddress,

        ## Specifies the user's employee ID (ldapDisplayName 'employeeID')
        [ValidateNotNull()]
        [System.String] $EmployeeID,

        ## Specifies the user's employee number (ldapDisplayName 'employeeNumber')
        [ValidateNotNull()]
        [System.String] $EmployeeNumber,

        ## Specifies a user's home directory path (ldapDisplayName 'homeDirectory')
        [ValidateNotNull()]
        [System.String] $HomeDirectory,

        ## Specifies a drive that is associated with the UNC path defined by the HomeDirectory property (ldapDisplayName 'homeDrive')
        [ValidateNotNull()]
        [System.String] $HomeDrive,

        ## Specifies the URL of the home page of the object (ldapDisplayName 'wWWHomePage')
        [ValidateNotNull()]
        [System.String] $HomePage,

        ## Specifies a path to the user's profile (ldapDisplayName 'profilePath')
        [ValidateNotNull()]
        [System.String] $ProfilePath,

        ## Specifies a path to the user's log on script (ldapDisplayName 'scriptPath')
        [ValidateNotNull()]
        [System.String] $LogonScript,

        ## Specifies the notes attached to the user's accoutn (ldapDisplayName 'info')
        [ValidateNotNull()]
        [System.String] $Notes,

        ## Specifies the user's office telephone number (ldapDisplayName 'telephoneNumber')
        [ValidateNotNull()]
        [System.String] $OfficePhone,

        ## Specifies the user's mobile phone number (ldapDisplayName 'mobile')
        [ValidateNotNull()]
        [System.String] $MobilePhone,

        ## Specifies the user's fax phone number (ldapDisplayName 'facsimileTelephoneNumber')
        [ValidateNotNull()]
        [System.String] $Fax,

        ## Specifies the user's home telephone number (ldapDisplayName 'homePhone')
        [ValidateNotNull()]
        [System.String] $HomePhone,

         ## Specifies the user's pager number (ldapDisplayName 'pager')
        [ValidateNotNull()]
        [System.String] $Pager,

        ## Specifies the user's IP telephony phone number (ldapDisplayName 'ipPhone')
        [ValidateNotNull()]
        [System.String] $IPPhone,

        ## Specifies the user's manager specified as a Distinguished Name (ldapDisplayName 'manager')
        [ValidateNotNull()]
        [System.String] $Manager,

        ## Specifies if the account is enabled (default True)
        [ValidateNotNull()]
        [System.Boolean] $Enabled = $true,

        ## Specifies whether the account password can be changed
        [ValidateNotNull()]
        [System.Boolean] $CannotChangePassword,

        ## Specifies whether the password of an account can expire
        [ValidateNotNull()]
        [System.Boolean] $PasswordNeverExpires,

        ## Specifies the Active Directory Domain Services instance to use to perform the task.
        [ValidateNotNull()]
        [System.String] $DomainController,

        ## Specifies the user account credentials to use to perform this task. Ideally this should just be called 'Credential' but is here for backwards compatibility
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $DomainAdministratorCredential,

        ## Specifies the authentication context type when testing user passwords #61
        [ValidateSet('Default','Negotiate')]
        [System.String] $PasswordAuthentication = 'Default'
    )

    Assert-Module -ModuleName 'ActiveDirectory';

    try
    {
        $adCommonParameters = Get-ADCommonParameters @PSBoundParameters;

        $adProperties = @();
        ## Create an array of the AD propertie names to retrieve from the property map
        foreach ($property in $adPropertyMap)
        {
            if ($property.ADProperty)
            {
                $adProperties += $property.ADProperty;
            }
            else
            {
                $adProperties += $property.Parameter;
            }
        }

        Write-Verbose -Message ($LocalizedData.RetrievingADUser -f $UserName, $DomainName);
        $adUser = Get-ADUser @adCommonParameters -Properties $adProperties;
        Write-Verbose -Message ($LocalizedData.ADUserIsPresent -f $UserName, $DomainName);
        $Ensure = 'Present';
    }
    catch [Microsoft.ActiveDirectory.Management.ADIdentityNotFoundException]
    {
        Write-Verbose -Message ($LocalizedData.ADUserNotPresent -f $UserName, $DomainName);
        $Ensure = 'Absent';
    }
    catch
    {
        Write-Error -Message ($LocalizedData.RetrievingADUserError -f $UserName, $DomainName);
        throw $_;
    }

    $targetResource = @{
        DomainName        = $DomainName;
        Password          = $Password;
        UserName          = $UserName;
        DistinguishedName = $adUser.DistinguishedName; ## Read-only property
        Ensure            = $Ensure;
        DomainController  = $DomainController;
    }

    ## Retrieve each property from the ADPropertyMap and add to the hashtable
    foreach ($property in $adPropertyMap)
    {
        if ($property.Parameter -eq 'Path') {
            ## The path returned is not the parent container
            if (-not [System.String]::IsNullOrEmpty($adUser.DistinguishedName))
            {
                $targetResource['Path'] = Get-ADObjectParentDN -DN $adUser.DistinguishedName;
            }
        }
        elseif ($property.ADProperty)
        {
            ## The AD property name is different to the function parameter to use this
            $targetResource[$property.Parameter] = $adUser.($property.ADProperty);
        }
        else
        {
            ## The AD property name matches the function parameter
            $targetResource[$property.Parameter] = $adUser.($property.Parameter);
        }
    }
    return $targetResource;

} #end function Get-TargetResource

function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        ## Name of the domain where the user account is located (only used if password is managed)
        [Parameter(Mandatory)]
        [System.String] $DomainName,

        # Specifies the Security Account Manager (SAM) account name of the user (ldapDisplayName 'sAMAccountName')
        [Parameter(Mandatory)]
        [System.String] $UserName,

        ## Specifies a new password value for an account
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $Password,

        ## Specifies whether the user account is created or deleted
        [ValidateSet('Present', 'Absent')]
        [System.String] $Ensure = 'Present',

        ## Specifies the common nane assigned to the user account (ldapDisplayName 'cn')
        [ValidateNotNull()]
        [System.String] $CommonName = $UserName,

        ## Specifies the UPN assigned to the user account (ldapDisplayName 'userPrincipalName')
        [ValidateNotNull()]
        [System.String] $UserPrincipalName,

        ## Specifies the display name of the object (ldapDisplayName 'displayName')
        [ValidateNotNull()]
        [System.String] $DisplayName,

        ## Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created
        [ValidateNotNull()]
        [System.String] $Path,

        ## Specifies the user's given name (ldapDisplayName 'givenName')
        [ValidateNotNull()]
        [System.String] $GivenName,

        ## Specifies the initials that represent part of a user's name (ldapDisplayName 'initials')
        [ValidateNotNull()]
        [System.String] $Initials,

        ## Specifies the user's last name or surname (ldapDisplayName 'sn')
        [ValidateNotNull()]
        [System.String] $Surname,

        ## Specifies a description of the object (ldapDisplayName 'description')
        [ValidateNotNull()]
        [System.String] $Description,

        ## Specifies the user's street address (ldapDisplayName 'streetAddress')
        [ValidateNotNull()]
        [System.String] $StreetAddress,

        ## Specifies the user's post office box number (ldapDisplayName 'postOfficeBox')
        [ValidateNotNull()]
        [System.String] $POBox,

        ## Specifies the user's town or city (ldapDisplayName 'l')
        [ValidateNotNull()]
        [System.String] $City,

        ## Specifies the user's or Organizational Unit's state or province (ldapDisplayName 'st')
        [ValidateNotNull()]
        [System.String] $State,

        ## Specifies the user's postal code or zip code (ldapDisplayName 'postalCode')
        [ValidateNotNull()]
        [System.String] $PostalCode,

        ## Specifies the country or region code for the user's language of choice (ldapDisplayName 'c')
        [ValidateNotNull()]
        [System.String] $Country,

        ## Specifies the user's department (ldapDisplayName 'department')
        [ValidateNotNull()]
        [System.String] $Department,

        ## Specifies the user's division (ldapDisplayName 'division')
        [ValidateNotNull()]
        [System.String] $Division,

        ## Specifies the user's company (ldapDisplayName 'company')
        [ValidateNotNull()]
        [System.String] $Company,

        ## Specifies the location of the user's office or place of business (ldapDisplayName 'physicalDeliveryOfficeName')
        [ValidateNotNull()]
        [System.String] $Office,

        ## Specifies the user's title (ldapDisplayName 'title')
        [ValidateNotNull()]
        [System.String] $JobTitle,

        ## Specifies the user's e-mail address (ldapDisplayName 'mail')
        [ValidateNotNull()]
        [System.String] $EmailAddress,

        ## Specifies the user's employee ID (ldapDisplayName 'employeeID')
        [ValidateNotNull()]
        [System.String] $EmployeeID,

        ## Specifies the user's employee number (ldapDisplayName 'employeeNumber')
        [ValidateNotNull()]
        [System.String] $EmployeeNumber,

        ## Specifies a user's home directory path (ldapDisplayName 'homeDirectory')
        [ValidateNotNull()]
        [System.String] $HomeDirectory,

        ## Specifies a drive that is associated with the UNC path defined by the HomeDirectory property (ldapDisplayName 'homeDrive')
        [ValidateNotNull()]
        [System.String] $HomeDrive,

        ## Specifies the URL of the home page of the object (ldapDisplayName 'wWWHomePage')
        [ValidateNotNull()]
        [System.String] $HomePage,

        ## Specifies a path to the user's profile (ldapDisplayName 'profilePath')
        [ValidateNotNull()]
        [System.String] $ProfilePath,

        ## Specifies a path to the user's log on script (ldapDisplayName 'scriptPath')
        [ValidateNotNull()]
        [System.String] $LogonScript,

        ## Specifies the notes attached to the user's accoutn (ldapDisplayName 'info')
        [ValidateNotNull()]
        [System.String] $Notes,

        ## Specifies the user's office telephone number (ldapDisplayName 'telephoneNumber')
        [ValidateNotNull()]
        [System.String] $OfficePhone,

        ## Specifies the user's mobile phone number (ldapDisplayName 'mobile')
        [ValidateNotNull()]
        [System.String] $MobilePhone,

        ## Specifies the user's fax phone number (ldapDisplayName 'facsimileTelephoneNumber')
        [ValidateNotNull()]
        [System.String] $Fax,

        ## Specifies the user's home telephone number (ldapDisplayName 'homePhone')
        [ValidateNotNull()]
        [System.String] $HomePhone,

         ## Specifies the user's pager number (ldapDisplayName 'pager')
        [ValidateNotNull()]
        [System.String] $Pager,

        ## Specifies the user's IP telephony phone number (ldapDisplayName 'ipPhone')
        [ValidateNotNull()]
        [System.String] $IPPhone,

        ## Specifies the user's manager specified as a Distinguished Name (ldapDisplayName 'manager')
        [ValidateNotNull()]
        [System.String] $Manager,

        ## Specifies if the account is enabled (default True)
        [ValidateNotNull()]
        [System.Boolean] $Enabled = $true,

        ## Specifies whether the account password can be changed
        [ValidateNotNull()]
        [System.Boolean] $CannotChangePassword,

        ## Specifies whether the password of an account can expire
        [ValidateNotNull()]
        [System.Boolean] $PasswordNeverExpires,

        ## Specifies the Active Directory Domain Services instance to use to perform the task.
        [ValidateNotNull()]
        [System.String] $DomainController,

        ## Specifies the user account credentials to use to perform this task. Ideally this should just be called 'Credential' but is here for backwards compatibility
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $DomainAdministratorCredential,

        ## Specifies the authentication context type when testing user passwords #61
        [ValidateSet('Default','Negotiate')]
        [System.String] $PasswordAuthentication = 'Default'
    )

    Assert-Parameters @PSBoundParameters;
    $targetResource = Get-TargetResource @PSBoundParameters;
    $isCompliant = $true;

    if ($Ensure -eq 'Absent')
    {
        if ($targetResource.Ensure -eq 'Present')
        {
            Write-Verbose -Message ($LocalizedData.ADUserNotDesiredPropertyState -f 'Ensure', $PSBoundParameters.Ensure, $targetResource.Ensure);
            $isCompliant = $false;
        }
    }
    else
    {
        ## Add common name, ensure and enabled as they may not be explicitly passed and we want to enumerate them
        $PSBoundParameters['Ensure'] = $Ensure;
        $PSBoundParameters['Enabled'] = $Enabled;

        foreach ($parameter in $PSBoundParameters.Keys)
        {
            if ($parameter -eq 'Password')
            {
                $testPasswordParams = @{
                    Username = $UserName;
                    Password = $Password;
                    DomainName = $DomainName;
                    PasswordAuthentication = $PasswordAuthentication;
                }
                if ($DomainAdministratorCredential)
                {
                    $testPasswordParams['DomainAdministratorCredential'] = $DomainAdministratorCredential;
                }
                if (-not (Test-Password @testPasswordParams))
                {
                    Write-Verbose -Message ($LocalizedData.ADUserNotDesiredPropertyState -f 'Password', '<Password>', '<Password>');
                    $isCompliant = $false;
                }
            }
            # Only check properties that are returned by Get-TargetResource
            elseif ($targetResource.ContainsKey($parameter))
            {
                ## This check is required to be able to explicitly remove values with an empty string, if required
                if (([System.String]::IsNullOrEmpty($PSBoundParameters.$parameter)) -and ([System.String]::IsNullOrEmpty($targetResource.$parameter)))
                {
                    # Both values are null/empty and therefore we are compliant
                }
                elseif ($PSBoundParameters.$parameter -ne $targetResource.$parameter)
                {
                    Write-Verbose -Message ($LocalizedData.ADUserNotDesiredPropertyState -f $parameter, $PSBoundParameters.$parameter, $targetResource.$parameter);
                    $isCompliant = $false;
                }
            }
        } #end foreach PSBoundParameter
    }

    return $isCompliant;

} #end function Test-TargetResource

function Set-TargetResource
{
    [CmdletBinding()]
    param
    (
        ## Name of the domain where the user account is located (only used if password is managed)
        [Parameter(Mandatory)]
        [System.String] $DomainName,

        # Specifies the Security Account Manager (SAM) account name of the user (ldapDisplayName 'sAMAccountName')
        [Parameter(Mandatory)]
        [System.String] $UserName,

        ## Specifies a new password value for an account
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $Password,

        ## Specifies whether the user account is created or deleted
        [ValidateSet('Present', 'Absent')]
        [System.String] $Ensure = 'Present',

        ## Specifies the common nane assigned to the user account (ldapDisplayName 'cn')
        [ValidateNotNull()]
        [System.String] $CommonName = $UserName,

        ## Specifies the UPN assigned to the user account (ldapDisplayName 'userPrincipalName')
        [ValidateNotNull()]
        [System.String] $UserPrincipalName,

        ## Specifies the display name of the object (ldapDisplayName 'displayName')
        [ValidateNotNull()]
        [System.String] $DisplayName,

        ## Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created
        [ValidateNotNull()]
        [System.String] $Path,

        ## Specifies the user's given name (ldapDisplayName 'givenName')
        [ValidateNotNull()]
        [System.String] $GivenName,

        ## Specifies the initials that represent part of a user's name (ldapDisplayName 'initials')
        [ValidateNotNull()]
        [System.String] $Initials,

        ## Specifies the user's last name or surname (ldapDisplayName 'sn')
        [ValidateNotNull()]
        [System.String] $Surname,

        ## Specifies a description of the object (ldapDisplayName 'description')
        [ValidateNotNull()]
        [System.String] $Description,

        ## Specifies the user's street address (ldapDisplayName 'streetAddress')
        [ValidateNotNull()]
        [System.String] $StreetAddress,

        ## Specifies the user's post office box number (ldapDisplayName 'postOfficeBox')
        [ValidateNotNull()]
        [System.String] $POBox,

        ## Specifies the user's town or city (ldapDisplayName 'l')
        [ValidateNotNull()]
        [System.String] $City,

        ## Specifies the user's or Organizational Unit's state or province (ldapDisplayName 'st')
        [ValidateNotNull()]
        [System.String] $State,

        ## Specifies the user's postal code or zip code (ldapDisplayName 'postalCode')
        [ValidateNotNull()]
        [System.String] $PostalCode,

        ## Specifies the country or region code for the user's language of choice (ldapDisplayName 'c')
        [ValidateNotNull()]
        [System.String] $Country,

        ## Specifies the user's department (ldapDisplayName 'department')
        [ValidateNotNull()]
        [System.String] $Department,

        ## Specifies the user's division (ldapDisplayName 'division')
        [ValidateNotNull()]
        [System.String] $Division,

        ## Specifies the user's company (ldapDisplayName 'company')
        [ValidateNotNull()]
        [System.String] $Company,

        ## Specifies the location of the user's office or place of business (ldapDisplayName 'physicalDeliveryOfficeName')
        [ValidateNotNull()]
        [System.String] $Office,

        ## Specifies the user's title (ldapDisplayName 'title')
        [ValidateNotNull()]
        [System.String] $JobTitle,

        ## Specifies the user's e-mail address (ldapDisplayName 'mail')
        [ValidateNotNull()]
        [System.String] $EmailAddress,

        ## Specifies the user's employee ID (ldapDisplayName 'employeeID')
        [ValidateNotNull()]
        [System.String] $EmployeeID,

        ## Specifies the user's employee number (ldapDisplayName 'employeeNumber')
        [ValidateNotNull()]
        [System.String] $EmployeeNumber,

        ## Specifies a user's home directory path (ldapDisplayName 'homeDirectory')
        [ValidateNotNull()]
        [System.String] $HomeDirectory,

        ## Specifies a drive that is associated with the UNC path defined by the HomeDirectory property (ldapDisplayName 'homeDrive')
        [ValidateNotNull()]
        [System.String] $HomeDrive,

        ## Specifies the URL of the home page of the object (ldapDisplayName 'wWWHomePage')
        [ValidateNotNull()]
        [System.String] $HomePage,

        ## Specifies a path to the user's profile (ldapDisplayName 'profilePath')
        [ValidateNotNull()]
        [System.String] $ProfilePath,

        ## Specifies a path to the user's log on script (ldapDisplayName 'scriptPath')
        [ValidateNotNull()]
        [System.String] $LogonScript,

        ## Specifies the notes attached to the user's accoutn (ldapDisplayName 'info')
        [ValidateNotNull()]
        [System.String] $Notes,

        ## Specifies the user's office telephone number (ldapDisplayName 'telephoneNumber')
        [ValidateNotNull()]
        [System.String] $OfficePhone,

        ## Specifies the user's mobile phone number (ldapDisplayName 'mobile')
        [ValidateNotNull()]
        [System.String] $MobilePhone,

        ## Specifies the user's fax phone number (ldapDisplayName 'facsimileTelephoneNumber')
        [ValidateNotNull()]
        [System.String] $Fax,

        ## Specifies the user's home telephone number (ldapDisplayName 'homePhone')
        [ValidateNotNull()]
        [System.String] $HomePhone,

         ## Specifies the user's pager number (ldapDisplayName 'pager')
        [ValidateNotNull()]
        [System.String] $Pager,

        ## Specifies the user's IP telephony phone number (ldapDisplayName 'ipPhone')
        [ValidateNotNull()]
        [System.String] $IPPhone,

        ## Specifies the user's manager specified as a Distinguished Name (ldapDisplayName 'manager')
        [ValidateNotNull()]
        [System.String] $Manager,

        ## Specifies if the account is enabled (default True)
        [ValidateNotNull()]
        [System.Boolean] $Enabled = $true,

        ## Specifies whether the account password can be changed
        [ValidateNotNull()]
        [System.Boolean] $CannotChangePassword,

        ## Specifies whether the password of an account can expire
        [ValidateNotNull()]
        [System.Boolean] $PasswordNeverExpires,

        ## Specifies the Active Directory Domain Services instance to use to perform the task.
        [ValidateNotNull()]
        [System.String] $DomainController,

        ## Specifies the user account credentials to use to perform this task. Ideally this should just be called 'Credential' but is here for backwards compatibility
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $DomainAdministratorCredential,

        ## Specifies the authentication context type when testing user passwords #61
        [ValidateSet('Default','Negotiate')]
        [System.String] $PasswordAuthentication = 'Default'
    )

    Assert-Parameters @PSBoundParameters;
    $targetResource = Get-TargetResource @PSBoundParameters;

    ## Add common name, ensure and enabled as they may not be explicitly passed
    $PSBoundParameters['Ensure'] = $Ensure;
    $PSBoundParameters['Enabled'] = $Enabled;

    if ($Ensure -eq 'Present')
    {
        if ($targetResource.Ensure -eq 'Absent') {
            ## User does not exist and needs creating
            $newADUserParams = Get-ADCommonParameters @PSBoundParameters -UseNameParameter;
            if ($PSBoundParameters.ContainsKey('Path'))
            {
                $newADUserParams['Path'] = $Path;
            }
            Write-Verbose -Message ($LocalizedData.AddingADUser -f $UserName);
            New-ADUser @newADUserParams -SamAccountName $UserName;
            ## Now retrieve the newly created user
            $targetResource = Get-TargetResource @PSBoundParameters;
        }

        $setADUserParams = Get-ADCommonParameters @PSBoundParameters;
        $replaceUserProperties = @{};
        $removeUserProperties = @{};
        foreach ($parameter in $PSBoundParameters.Keys)
        {
            ## Only check/action properties specified/declared parameters that match one of the function's
            ## parameters. This will ignore common parameters such as -Verbose etc.
            if ($targetResource.ContainsKey($parameter))
            {
                if ($parameter -eq 'Path' -and ($PSBoundParameters.Path -ne $targetResource.Path))
                {
                    ## Cannot move users by updating the DistinguishedName property
                    $adCommonParameters = Get-ADCommonParameters @PSBoundParameters;
                    ## Using the SamAccountName for identity with Move-ADObject does not work, use the DN instead
                    $adCommonParameters['Identity'] = $targetResource.DistinguishedName;
                    Write-Verbose -Message ($LocalizedData.MovingADUser -f $targetResource.Path, $PSBoundParameters.Path);
                    Move-ADObject @adCommonParameters -TargetPath $PSBoundParameters.Path;
                }
                elseif ($parameter -eq 'CommonName' -and ($PSBoundParameters.CommonName -ne $targetResource.CommonName))
                {
                    ## Cannot rename users by updating the CN property directly
                    $adCommonParameters = Get-ADCommonParameters @PSBoundParameters;
                    ## Using the SamAccountName for identity with Rename-ADObject does not work, use the DN instead
                    $adCommonParameters['Identity'] = $targetResource.DistinguishedName;
                    Write-Verbose -Message ($LocalizedData.RenamingADUser -f $targetResource.CommonName, $PSBoundParameters.CommonName);
                    Rename-ADObject @adCommonParameters -NewName $PSBoundParameters.CommonName;
                }
                elseif ($parameter -eq 'Password')
                {
                    $adCommonParameters = Get-ADCommonParameters @PSBoundParameters;
                    Write-Verbose -Message ($LocalizedData.SettingADUserPassword -f $UserName);
                    Set-ADAccountPassword @adCommonParameters -Reset -NewPassword $Password.Password;
                }
                elseif ($parameter -eq 'Enabled' -and ($PSBoundParameters.$parameter -ne $targetResource.$parameter))
                {
                    ## We cannot enable/disable an account with -Add or -Replace parameters, but inform that
                    ## we will change this as it is out of compliance (it always gets set anyway)
                    Write-Verbose -Message ($LocalizedData.UpdatingADUserProperty -f $parameter, $PSBoundParameters.$parameter);
                }
                elseif ($PSBoundParameters.$parameter -ne $targetResource.$parameter)
                {
                    ## Find the associated AD property
                    $adProperty = $adPropertyMap | Where-Object { $_.Parameter -eq $parameter };

                    if ([System.String]::IsNullOrEmpty($adProperty))
                    {
                        ## We can't do anything is an empty AD property!
                    }
                    elseif ([System.String]::IsNullOrEmpty($PSBoundParameters.$parameter))
                    {
                        ## We are removing properties
                        ## Only remove if the existing value in not null or empty
                        if (-not ([System.String]::IsNullOrEmpty($targetResource.$parameter)))
                        {
                            Write-Verbose -Message ($LocalizedData.RemovingADUserProperty -f $parameter, $PSBoundParameters.$parameter);
                            if ($adProperty.UseCmdletParameter -eq $true)
                            {
                                ## We need to pass the parameter explicitly to Set-ADUser, not via -Remove
                                $setADUserParams[$adProperty.Parameter] = $PSBoundParameters.$parameter;
                            }
                            elseif ([System.String]::IsNullOrEmpty($adProperty.ADProperty))
                            {
                                $removeUserProperties[$adProperty.Parameter] = $targetResource.$parameter;
                            }
                            else
                            {
                                $removeUserProperties[$adProperty.ADProperty] = $targetResource.$parameter;
                            }
                        }
                    } #end if remove existing value
                    else
                    {
                        ## We are replacing the existing value
                        Write-Verbose -Message ($LocalizedData.UpdatingADUserProperty -f $parameter, $PSBoundParameters.$parameter);
                        if ($adProperty.UseCmdletParameter -eq $true)
                        {
                            ## We need to pass the parameter explicitly to Set-ADUser, not via -Replace
                            $setADUserParams[$adProperty.Parameter] = $PSBoundParameters.$parameter;
                        }
                        elseif ([System.String]::IsNullOrEmpty($adProperty.ADProperty))
                        {
                            $replaceUserProperties[$adProperty.Parameter] = $PSBoundParameters.$parameter;
                        }
                        else
                        {
                            $replaceUserProperties[$adProperty.ADProperty] = $PSBoundParameters.$parameter;
                        }
                    } #end if replace existing value
                }

            } #end if TargetResource parameter
        } #end foreach PSBoundParameter

        ## Only pass -Remove and/or -Replace if we have something to set/change
        if ($replaceUserProperties.Count -gt 0)
        {
            $setADUserParams['Replace'] = $replaceUserProperties;
        }
        if ($removeUserProperties.Count -gt 0)
        {
            $setADUserParams['Remove'] = $removeUserProperties;
        }

        Write-Verbose -Message ($LocalizedData.UpdatingADUser -f $UserName);
        [ref] $null = Set-ADUser @setADUserParams -Enabled $Enabled;
    }
    elseif (($Ensure -eq 'Absent') -and ($targetResource.Ensure -eq 'Present'))
    {
        ## User exists and needs removing
        Write-Verbose ($LocalizedData.RemovingADUser -f $UserName);
        $adCommonParameters = Get-ADCommonParameters @PSBoundParameters;
        [ref] $null = Remove-ADUser @adCommonParameters -Confirm:$false;
    }

} #end function Set-TargetResource

# Internal function to validate unsupported options/configurations
function Assert-Parameters
{
    [CmdletBinding()]
    param
    (
        [ValidateNotNull()]
        [System.Management.Automation.PSCredential] $Password,

        [ValidateNotNull()]
        [System.Boolean] $Enabled = $true,

        [Parameter(ValueFromRemainingArguments)]
        $IgnoredArguments
    )

    ## We cannot test/set passwords on disabled AD accounts
    if (($PSBoundParameters.ContainsKey('Password')) -and ($Enabled -eq $false))
    {
        $throwInvalidArgumentErrorParams = @{
            ErrorId = 'xADUser_DisabledAccountPasswordConflict';
            ErrorMessage = $LocalizedData.PasswordParameterConflictError -f 'Enabled', $false, 'Password';
        }
        ThrowInvalidArgumentError @throwInvalidArgumentErrorParams;
    }

} #end function Assert-Parameters

# Internal function to test the validity of a user's password.
function Test-Password
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory)]
        [System.String] $DomainName,

        [Parameter(Mandatory)]
        [System.String] $UserName,

        [Parameter(Mandatory)]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $Password,

        [ValidateNotNull()]
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.CredentialAttribute()]
        $DomainAdministratorCredential,

        ## Specifies the authentication context type when testing user passwords #61
        [Parameter(Mandatory)]
        [ValidateSet('Default','Negotiate')]
        [System.String] $PasswordAuthentication
    )

    Write-Verbose -Message ($LocalizedData.CreatingADDomainConnection -f $DomainName);
    Add-Type -AssemblyName 'System.DirectoryServices.AccountManagement';

    if ($DomainAdministratorCredential)
    {
        $principalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext(
                                [System.DirectoryServices.AccountManagement.ContextType]::Domain,
                                $DomainName,
                                $DomainAdministratorCredential.UserName,
                                $DomainAdministratorCredential.GetNetworkCredential().Password
                            );
    }
    else
    {
        $principalContext = New-Object System.DirectoryServices.AccountManagement.PrincipalContext(
                                [System.DirectoryServices.AccountManagement.ContextType]::Domain,
                                $DomainName,
                                $null,
                                $null
                            );
    }
    Write-Verbose -Message ($LocalizedData.CheckingADUserPassword -f $UserName);

    if ($PasswordAuthentication -eq 'Negotiate')
    {
        return $principalContext.ValidateCredentials(
            $UserName,
            $Password.GetNetworkCredential().Password,
            [System.DirectoryServices.AccountManagement.ContextOptions]::Negotiate -bor
                [System.DirectoryServices.AccountManagement.ContextOptions]::Signing -bor
                    [System.DirectoryServices.AccountManagement.ContextOptions]::Sealing
        );
    }
    else
    {
        ## Use default authentication context
        return $principalContext.ValidateCredentials(
            $UserName,
            $Password.GetNetworkCredential().Password
        );
    }

} #end function Test-Password

## Import the common AD functions
$adCommonFunctions = Join-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -ChildPath '\MSFT_xADCommon\MSFT_xADCommon.ps1';
. $adCommonFunctions;

Export-ModuleMember -Function *-TargetResource