Add new resource xADObjectEnabledState

dsccommunity · Jun 4, 2019 · d16a1c3 · d16a1c3
1 parent c39f7ef
commit d16a1c3
Show file tree

Hide file tree

Showing 11 changed files with 1,399 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,10 @@
     - Common Tests - Validate Markdown Links ([Issue #280](https://github.com/PowerShell/xActiveDirectory/issues/280))
     - Common Tests - Validate Localization ([Issue #281](https://github.com/PowerShell/xActiveDirectory/issues/281))
     - Common Tests - Validate Example Files ([Issue #279](https://github.com/PowerShell/xActiveDirectory/issues/279))
+  - Added new resource xADObjectEnabledState. This resource should be
+    used to enforce the `Enabled` property of computer accounts. This
+    resource replaces the deprecated `Enabled` property in the resource
+    xADComputer.
 - Changes to xADComputer
   - Refactored the resource and the unit tests.
   - BREAKING CHANGE: The `Enabled` property is **DEPRECATED** and is no

diff --git a/DSCResources/MSFT_xADObjectEnabledState/MSFT_xADObjectEnabledState.psm1 b/DSCResources/MSFT_xADObjectEnabledState/MSFT_xADObjectEnabledState.psm1
@@ -0,0 +1,378 @@
+$script:resourceModulePath = Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent
+$script:modulesFolderPath = Join-Path -Path $script:resourceModulePath -ChildPath 'Modules'
+
+$script:localizationModulePath = Join-Path -Path $script:modulesFolderPath -ChildPath 'xActiveDirectory.Common'
+Import-Module -Name (Join-Path -Path $script:localizationModulePath -ChildPath 'xActiveDirectory.Common.psm1')
+
+$script:dscResourcePath = Split-Path -Path $PSScriptRoot -Parent
+Import-Module -Name (Join-Path -Path $script:dscResourcePath -ChildPath '\MSFT_xADCommon\MSFT_xADCommon.psm1')
+
+$script:localizedData = Get-LocalizedData -ResourceName 'MSFT_xADObjectEnabledState'
+
+<#
+    .SYNOPSIS
+        Returns the current state of the property Enabled of an Active Directory
+        object.
+
+    .PARAMETER Identity
+        Specifies the identity of an object that has the object class specified
+        in the parameter ObjectClass. When ObjectClass is set to 'Computer' then
+        this property can be set to either distinguished name, GUID (objectGUID),
+        security identifier (objectSid), or security Accounts Manager account
+        name (sAMAccountName).
+
+    .PARAMETER ObjectClass
+        Specifies the object class.
+
+    .PARAMETER Enabled
+        Specifies the value of the Enabled property.
+
+        Not used in Get-TargetResource.
+
+    .PARAMETER DomainController
+        Specifies the Active Directory Domain Services instance to connect to perform the task.
+
+        Used by Get-ADCommonParameters and is returned as a common parameter.
+
+    .PARAMETER Credential
+        Specifies the user account credentials to use to perform the task.
+
+        Used by Get-ADCommonParameters and is returned as a common parameter.
+#>
+function Get-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Identity,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Computer')]
+        [System.String]
+        $ObjectClass,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNull()]
+        [System.Boolean]
+        $Enabled,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.String]
+        $DomainController,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.Management.Automation.PSCredential]
+        [System.Management.Automation.CredentialAttribute()]
+        $Credential
+    )
+
+    Assert-Module -ModuleName 'ActiveDirectory' -ImportModule
+
+    <#
+        These are properties that have no corresponding property in a
+        Computer account object.
+    #>
+    $getTargetResourceReturnValue = @{
+        Identity         = $Identity
+        ObjectClass      = $ObjectClass
+        Enabled          = $false
+        DomainController = $DomainController
+        Credential       = $Credential
+    }
+
+    switch ($ObjectClass)
+    {
+        'Computer'
+        {
+            $getADComputerResult = $null
+
+            try
+            {
+                Write-Verbose -Message ($script:localizedData.RetrievingComputerAccount -f $Identity)
+
+                $getADComputerParameters = Get-ADCommonParameters @PSBoundParameters
+                $getADComputerParameters['Properties'] = 'Enabled'
+
+                # If the computer account is not found Get-ADComputer will throw an error.
+                $getADComputerResult = Get-ADComputer @getADComputerParameters
+
+                $getTargetResourceReturnValue['Enabled'] = $getADComputerResult.Enabled
+
+                if ($getADComputerResult.Enabled)
+                {
+                    Write-Verbose -Message $script:localizedData.ComputerAccountEnabled
+                }
+                else
+                {
+                    Write-Verbose -Message $script:localizedData.ComputerAccountDisabled
+                }
+            }
+            catch
+            {
+                $errorMessage = $script:localizedData.FailedToRetrieveComputerAccount -f $Identity
+                New-InvalidOperationException -Message $errorMessage -ErrorRecord $_
+            }
+        }
+    }
+
+    return $getTargetResourceReturnValue
+}
+
+<#
+    .SYNOPSIS
+        Determines if the property Enabled of the Active Directory object is in
+        the desired state.
+
+    .PARAMETER Identity
+        Specifies the identity of an object that has the object class specified
+        in the parameter ObjectClass. When ObjectClass is set to 'Computer' then
+        this property can be set to either distinguished name, GUID (objectGUID),
+        security identifier (objectSid), or security Accounts Manager account
+        name (sAMAccountName).
+
+    .PARAMETER ObjectClass
+        Specifies the object class.
+
+    .PARAMETER Enabled
+        Specifies the value of the Enabled property.
+
+    .PARAMETER DomainController
+        Specifies the Active Directory Domain Services instance to connect to
+        perform the task.
+
+    .PARAMETER Credential
+        Specifies the user account credentials to use to perform the task.
+#>
+function Test-TargetResource
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Identity,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Computer')]
+        [System.String]
+        $ObjectClass,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNull()]
+        [System.Boolean]
+        $Enabled,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.String]
+        $DomainController,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.Management.Automation.PSCredential]
+        [System.Management.Automation.CredentialAttribute()]
+        $Credential
+    )
+
+    Write-Verbose -Message (
+        $script:localizedData.TestConfiguration -f $Identity, $ObjectClass
+    )
+
+    $getTargetResourceParameters = @{
+        Identity         = $Identity
+        ObjectClass      = $ObjectClass
+        Enabled          = $Enabled
+        DomainController = $DomainController
+        Credential       = $Credential
+    }
+
+    # Need the @() around this to get a new array to enumerate.
+    @($getTargetResourceParameters.Keys) | ForEach-Object {
+        if (-not $PSBoundParameters.ContainsKey($_))
+        {
+            $getTargetResourceParameters.Remove($_)
+        }
+    }
+
+    $getTargetResourceResult = Get-TargetResource @getTargetResourceParameters
+
+    $compareTargetResourceStateParameters = @{
+        CurrentValues = $getTargetResourceResult
+        DesiredValues = $PSBoundParameters
+        Properties    = @('Enabled')
+    }
+
+    $compareTargetResourceStateResult = Compare-ResourcePropertyState @compareTargetResourceStateParameters
+
+    if ($false -in $compareTargetResourceStateResult.InDesiredState)
+    {
+        $testTargetResourceReturnValue = $false
+    }
+    else
+    {
+        $testTargetResourceReturnValue = $true
+    }
+
+    switch ($ObjectClass)
+    {
+        'Computer'
+        {
+            if ($testTargetResourceReturnValue)
+            {
+                Write-Verbose -Message ($script:localizedData.ComputerAccountInDesiredState -f $Identity)
+            }
+            else
+            {
+                Write-Verbose -Message ($script:localizedData.ComputerAccountNotInDesiredState -f $Identity)
+            }
+        }
+    }
+
+    return $testTargetResourceReturnValue
+}
+
+<#
+    .SYNOPSIS
+        Sets the property Enabled of the Active Directory object.
+
+    .PARAMETER Identity
+        Specifies the identity of an object that has the object class specified
+        in the parameter ObjectClass. When ObjectClass is set to 'Computer' then
+        this property can be set to either distinguished name, GUID (objectGUID),
+        security identifier (objectSid), or security Accounts Manager account
+        name (sAMAccountName).
+
+    .PARAMETER ObjectClass
+        Specifies the object class.
+
+    .PARAMETER Enabled
+        Specifies the value of the Enabled property.
+
+    .PARAMETER DomainController
+        Specifies the Active Directory Domain Services instance to connect to
+        perform the task.
+
+    .PARAMETER Credential
+        Specifies the user account credentials to use to perform the task.
+#>
+function Set-TargetResource
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Identity,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Computer')]
+        [System.String]
+        $ObjectClass,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNull()]
+        [System.Boolean]
+        $Enabled,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.String]
+        $DomainController,
+
+        [Parameter()]
+        [ValidateNotNull()]
+        [System.Management.Automation.PSCredential]
+        [System.Management.Automation.CredentialAttribute()]
+        $Credential
+    )
+
+    $getTargetResourceParameters = @{
+        Identity         = $Identity
+        ObjectClass      = $ObjectClass
+        Enabled          = $Enabled
+        DomainController = $DomainController
+        Credential       = $Credential
+    }
+
+    # Need the @() around this to get a new array to enumerate.
+    @($getTargetResourceParameters.Keys) | ForEach-Object {
+        if (-not $PSBoundParameters.ContainsKey($_))
+        {
+            $getTargetResourceParameters.Remove($_)
+        }
+    }
+
+    $getTargetResourceResult = Get-TargetResource @getTargetResourceParameters
+
+    $compareTargetResourceStateParameters = @{
+        CurrentValues = $getTargetResourceResult
+        DesiredValues = $PSBoundParameters
+        Properties    = @('Enabled')
+    }
+
+    $compareTargetResourceStateResult = Compare-ResourcePropertyState @compareTargetResourceStateParameters
+
+    # Get all properties that are not in desired state.
+    $propertiesNotInDesiredState = $compareTargetResourceStateResult | Where-Object -FilterScript {
+        -not $_.InDesiredState
+    }
+
+    if ($propertiesNotInDesiredState.Where( { $_.ParameterName -eq 'Enabled' }))
+    {
+        $commonParameters = Get-ADCommonParameters @PSBoundParameters
+
+        switch ($ObjectClass)
+        {
+            'Computer'
+            {
+                $setADComputerParameters = $commonParameters.Clone()
+                $setADComputerParameters['Enabled'] = $Enabled
+
+                Set-DscADComputer -Parameters $setADComputerParameters
+
+                if ($Enabled)
+                {
+                    Write-Verbose -Message (
+                        $script:localizedData.ComputerAccountHasBeenEnabled -f $Identity
+                    )
+                }
+                else
+                {
+                    Write-Verbose -Message (
+                        $script:localizedData.ComputerAccountHasBeenDisabled -f $Identity
+                    )
+                }
+            }
+        }
+    }
+}
+
+<#
+    .SYNOPSIS
+        This is a wrapper for Set-ADComputer.
+
+    .PARAMETER Parameters
+        A hash table containing all parameters that will be passed trough to
+        Set-ADComputer.
+
+    .NOTES
+        This is needed because of how Pester is unable to handle mocking the
+        cmdlet Set-ADComputer.
+#>
+function Set-DscADComputer
+{
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.Collections.Hashtable]
+        $Parameters
+    )
+
+    Set-ADComputer @Parameters | Out-Null
+}
diff --git a/DSCResources/MSFT_xADObjectEnabledState/MSFT_xADObjectEnabledState.schema.mof b/DSCResources/MSFT_xADObjectEnabledState/MSFT_xADObjectEnabledState.schema.mof
@@ -0,0 +1,9 @@
+[ClassVersion("1.0.0.0"), FriendlyName("xADObjectEnabledState")]
+class MSFT_xADObjectEnabledState : OMI_BaseResource
+{
+    [Key, Description("Specifies the identity of an object that has the object class specified in the parameter ObjectClass. When ObjectClass is set to 'Computer' then this property can be set to either distinguished name, GUID (objectGUID), security identifier (objectSid), or security Accounts Manager account name (sAMAccountName).")] String Identity;
+    [Key, Description("Specifies the object class."), ValueMap{"Computer"}, Values{"Computer"}] String ObjectClass;
+    [Required, Description("Specifies the value of the Enabled property.")] Boolean Enabled;
+    [Write, Description("Specifies the Active Directory Domain Services instance to connect to perform the task.")] String DomainController;
+    [Write, Description("Specifies the user account credentials to use to perform the task."), EmbeddedInstance("MSFT_Credential")] String Credential;
+};