Changes to ADDomain

- BREAKING CHANGE: Renamed the parameter `DomainAdministratorCredential` to `Credential` to better indicate that it is possible to impersonate any credential with enough permission to perform the task [issue dsccommunity#269).
johlju · Jul 29, 2019 · dd73e91 · dd73e91
1 parent 3536b88
commit dd73e91
Show file tree

Hide file tree

Showing 8 changed files with 84 additions and 59 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -64,6 +64,9 @@
     Creation ([issue #414](https://github.com/PowerShell/ActiveDirectoryDsc/issues/414)).
   - Added comment-based help ([issue #340](https://github.com/PowerShell/ActiveDirectoryDsc/issues/340)).
 - Changes to ADDomain
+  - BREAKING CHANGE: Renamed the parameter `DomainAdministratorCredential`
+    to `Credential` to better indicate that it is possible to impersonate
+    any credential with enough permission to perform the task ([issue #269](https://github.com/PowerShell/ActiveDirectoryDsc/issues/269)).
   - Updated tests and replaced `Write-Error` with `throw`
     ([issue #332](https://github.com/PowerShell/ActiveDirectoryDsc/pull/332)).
   - Added comment-based help ([issue #335](https://github.com/PowerShell/ActiveDirectoryDsc/issues/335)).

diff --git a/DSCResources/MSFT_ADDomain/MSFT_ADDomain.psm1 b/DSCResources/MSFT_ADDomain/MSFT_ADDomain.psm1
@@ -53,8 +53,9 @@ function Get-TrackingFilename
     .PARAMETER DomainName
         The fully qualified domain name (FQDN) of the new domain.
 
-    .PARAMETER DomainAdministratorCredential
-        Credentials used to query for domain existence.
+    .PARAMETER Credential
+        Specifies the user name and password that corresponds to the account
+        used to install the domain controller.
 
     .PARAMETER SafemodeAdministratorPassword
         Password for the administrator account when the computer is started in Safe Mode.
@@ -95,7 +96,7 @@ function Get-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $DomainAdministratorCredential,
+        $Credential,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
@@ -164,8 +165,8 @@ function Get-TargetResource
             else
             {
                 Write-Verbose ($script:localizedData.QueryDomainWithCredential -f $domainFQDN)
-                $domain = Get-ADDomain -Identity $domainFQDN -Credential $DomainAdministratorCredential -ErrorAction Stop
-                $forest = Get-ADForest -Identity $domain.Forest -Credential $DomainAdministratorCredential -ErrorAction Stop
+                $domain = Get-ADDomain -Identity $domainFQDN -Credential $Credential -ErrorAction Stop
+                $forest = Get-ADForest -Identity $domain.Forest -Credential $Credential -ErrorAction Stop
             }
 
             <#
@@ -237,8 +238,9 @@ function Get-TargetResource
     .PARAMETER DomainName
         The fully qualified domain name (FQDN) of the new domain.
 
-    .PARAMETER DomainAdministratorCredential
-        Credentials used to query for domain existence.
+    .PARAMETER Credential
+        Specifies the user name and password that corresponds to the account
+        used to install the domain controller.
 
     .PARAMETER SafemodeAdministratorPassword
         Password for the administrator account when the computer is started in Safe Mode.
@@ -279,7 +281,7 @@ function Test-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $DomainAdministratorCredential,
+        $Credential,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
@@ -376,8 +378,9 @@ function Test-TargetResource
     .PARAMETER DomainName
         The fully qualified domain name (FQDN) of the new domain.
 
-    .PARAMETER DomainAdministratorCredential
-        Credentials used to query for domain existence.
+    .PARAMETER Credential
+        Specifies the user name and password that corresponds to the account
+        used to install the domain controller.
 
     .PARAMETER SafemodeAdministratorPassword
         Password for the administrator account when the computer is started in Safe Mode.
@@ -429,7 +432,7 @@ function Set-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $DomainAdministratorCredential,
+        $Credential,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
@@ -517,7 +520,7 @@ function Set-TargetResource
     if ($PSBoundParameters.ContainsKey('ParentDomainName'))
     {
         Write-Verbose -Message ($script:localizedData.CreatingChildDomain -f $DomainName, $ParentDomainName)
-        $installADDSParams['Credential'] = $DomainAdministratorCredential
+        $installADDSParams['Credential'] = $Credential
         $installADDSParams['NewDomainName'] = $DomainName
         $installADDSParams['ParentDomainName'] = $ParentDomainName
         $installADDSParams['DomainType'] = 'ChildDomain'

diff --git a/DSCResources/MSFT_ADDomain/MSFT_ADDomain.schema.mof b/DSCResources/MSFT_ADDomain/MSFT_ADDomain.schema.mof
@@ -2,7 +2,7 @@
 class MSFT_ADDomain : OMI_BaseResource
 {
     [Key, Description("The fully qualified domain name (FQDN) of the new domain.")] String DomainName;
-    [Required, Description("Credentials used to query for domain existence."), EmbeddedInstance("MSFT_Credential")] String DomainAdministratorCredential;
+    [Required, Description("Specifies the user name and password that corresponds to the account used to install the domain controller."), EmbeddedInstance("MSFT_Credential")] String Credential;
     [Required, Description("Password for the administrator account when the computer is started in Safe Mode."), EmbeddedInstance("MSFT_Credential")] String SafemodeAdministratorPassword;
     [Write, Description("Fully qualified domain name (FQDN) of the parent domain.")] String ParentDomainName;
     [Write, Description("NetBIOS name for the new domain.")] String DomainNetbiosName;

diff --git a/Examples/Resources/ADDomain/1-NewForest_Config.ps1 b/Examples/Resources/ADDomain/1-NewForest_Config.ps1
@@ -30,7 +30,12 @@ Configuration NewForest_Config
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $DomainAdministratorCredential
+        $Credential,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $SafeModePassword
     )
 
     Import-DscResource -ModuleName PSDscResources
@@ -53,8 +58,8 @@ Configuration NewForest_Config
         ADDomain $Node.DomainName
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $DomainAdministratorCredential
-            SafemodeAdministratorPassword = $DomainAdministratorCredential
+            Credential                    = $Credential
+            SafemodeAdministratorPassword = $SafeModePassword
             ForestMode                    = $Node.FFL
         }
     }

diff --git a/Examples/Resources/ADDomain/2-NewChildDomain_Config.ps1 b/Examples/Resources/ADDomain/2-NewChildDomain_Config.ps1
@@ -30,7 +30,12 @@ Configuration NewChildDomain_Config
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $DomainAdministratorCredential
+        $Credential,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.PSCredential]
+        $SafeModePassword
     )
 
     Import-DscResource -ModuleName PSDscResources
@@ -53,8 +58,8 @@ Configuration NewChildDomain_Config
         ADDomain $Node.DomainName
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $DomainAdministratorCredential
-            SafemodeAdministratorPassword = $DomainAdministratorCredential
+            Credential                    = $Credential
+            SafemodeAdministratorPassword = $SafeModePassword
             DomainMode                    = $Node.DFL
             ParentDomainName              = $node.ParentDomain
         }

diff --git a/Examples/Resources/ADDomain/3-NewForestwithParentAndChildDomain_Config.ps1 b/Examples/Resources/ADDomain/3-NewForestwithParentAndChildDomain_Config.ps1
@@ -28,20 +28,22 @@ Configuration NewForestWithParentAndChildDomain_Config
     param
     (
         [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $SafemodeAdministratorCred,
+        $Credential,
 
         [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $DomainCred,
+        $SafeModePassword,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $DnsDelegationCred,
+        $DnsDelegationCredential,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $NewADUserCred
+        $NewADUserPassword
     )
 
     Import-DscResource -ModuleName ActiveDirectoryDsc
@@ -57,28 +59,31 @@ Configuration NewForestWithParentAndChildDomain_Config
         ADDomain 'FirstDS'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domainCred
-            SafemodeAdministratorPassword = $SafemodeAdministratorCred
-            DnsDelegationCredential       = $DnsDelegationCred
+            Credential                    = $Credential
+            SafeModeAdministratorPassword = $SafeModePassword
+            DnsDelegationCredential       = $DnsDelegationCredential
+
             DependsOn                     = '[WindowsFeature]ADDSInstall'
         }
 
         WaitForADDomain 'DscForestWait'
         {
             DomainName           = $Node.DomainName
-            DomainUserCredential = $domainCred
+            DomainUserCredential = $Credential
             RetryCount           = $Node.RetryCount
             RetryIntervalSec     = $Node.RetryIntervalSec
+
             DependsOn            = '[ADDomain]FirstDS'
         }
 
         ADUser 'FirstUser'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domaincred
+            DomainAdministratorCredential = $Credential
             UserName                      = 'dummy'
-            Password                      = $NewADUserCred
+            Password                      = $NewADUserPassword
             Ensure                        = 'Present'
+
             DependsOn                     = '[WaitForADDomain]DscForestWait'
         }
 
@@ -95,18 +100,20 @@ Configuration NewForestWithParentAndChildDomain_Config
         WaitForADDomain 'DscForestWait'
         {
             DomainName           = $Node.ParentDomainName
-            DomainUserCredential = $domainCred
+            DomainUserCredential = $Credential
             RetryCount           = $Node.RetryCount
             RetryIntervalSec     = $Node.RetryIntervalSec
+
             DependsOn            = '[WindowsFeature]ADDSInstall'
         }
 
         ADDomain 'ChildDS'
         {
             DomainName                    = $Node.DomainName
             ParentDomainName              = $Node.ParentDomainName
-            DomainAdministratorCredential = $domainCred
-            SafemodeAdministratorPassword = $SafemodeAdministratorCred
+            DomainAdministratorCredential = $Credential
+            SafeModeAdministratorPassword = $SafeModePassword
+
             DependsOn                     = '[WaitForADDomain]DscForestWait'
         }
     }

diff --git a/Examples/Resources/ADDomain/4-NewDomainWithTwoDCs_Config.ps1 b/Examples/Resources/ADDomain/4-NewDomainWithTwoDCs_Config.ps1
@@ -30,20 +30,22 @@ Configuration NewDomainWithTwoDCs_Config
     param
     (
         [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $SafemodeAdministratorCred,
+        $Credential,
 
         [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $domainCred,
+        $SafeModePassword,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $DNSDelegationCred,
+        $DnsDelegationCredential,
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $NewADUserCred
+        $NewADUserPassword
     )
 
     Import-DscResource -ModuleName ActiveDirectoryDsc
@@ -59,16 +61,16 @@ Configuration NewDomainWithTwoDCs_Config
         ADDomain 'FirstDS'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domainCred
-            SafemodeAdministratorPassword = $SafemodeAdministratorCred
-            DnsDelegationCredential       = $DNSDelegationCred
+            Credential                    = $Credential
+            SafeModeAdministratorPassword = $SafeModePassword
+            DnsDelegationCredential       = $DnsDelegationCredential
             DependsOn                     = '[WindowsFeature]ADDSInstall'
         }
 
         WaitForADDomain 'DscForestWait'
         {
             DomainName           = $Node.DomainName
-            DomainUserCredential = $domainCred
+            DomainUserCredential = $Credential
             RetryCount           = $Node.RetryCount
             RetryIntervalSec     = $Node.RetryIntervalSec
             DependsOn            = '[ADDomain]FirstDS'
@@ -77,9 +79,9 @@ Configuration NewDomainWithTwoDCs_Config
         ADUser 'FirstUser'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domainCred
+            DomainAdministratorCredential = $Credential
             UserName                      = 'dummy'
-            Password                      = $NewADUserCred
+            Password                      = $NewADUserPassword
             Ensure                        = 'Present'
             DependsOn                     = '[WaitForADDomain]DscForestWait'
         }
@@ -96,7 +98,7 @@ Configuration NewDomainWithTwoDCs_Config
         WaitForADDomain 'DscForestWait'
         {
             DomainName           = $Node.DomainName
-            DomainUserCredential = $domainCred
+            DomainUserCredential = $Credential
             RetryCount           = $Node.RetryCount
             RetryIntervalSec     = $Node.RetryIntervalSec
             DependsOn            = '[WindowsFeature]ADDSInstall'
@@ -105,8 +107,8 @@ Configuration NewDomainWithTwoDCs_Config
         ADDomainController 'SecondDC'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domainCred
-            SafemodeAdministratorPassword = $SafemodeAdministratorCred
+            DomainAdministratorCredential = $Credential
+            SafeModeAdministratorPassword = $SafeModePassword
             DependsOn                     = '[WaitForADDomain]DscForestWait'
         }
     }

diff --git a/Tests/Unit/MSFT_ADDomain.Tests.ps1 b/Tests/Unit/MSFT_ADDomain.Tests.ps1
@@ -66,8 +66,8 @@ try
         )
 
         $testDefaultParams = @{
-            DomainAdministratorCredential = $testAdminCredential
-            SafemodeAdministratorPassword = $testAdminCredential
+            Credential = $testAdminCredential
+            SafeModeAdministratorPassword = $testAdminCredential
         }
 
         #region Function Get-TargetResource
@@ -220,8 +220,8 @@ try
             )
 
             $testDefaultParams = @{
-                DomainAdministratorCredential = $testAdminCredential
-                SafemodeAdministratorPassword = $testAdminCredential
+                Credential = $testAdminCredential
+                SafeModeAdministratorPassword = $testAdminCredential
             }
 
             $stubDomain = @{
@@ -352,15 +352,15 @@ try
 
             $newForestParams = @{
                 DomainName = $testDomainName
-                DomainAdministratorCredential = $testAdminCredential
-                SafemodeAdministratorPassword = $testSafemodeCredential
+                Credential = $testAdminCredential
+                SafeModeAdministratorPassword = $testSafemodeCredential
             }
 
             $newDomainParams = @{
                 DomainName = $testDomainName
                 ParentDomainName = $testParentDomainName
-                DomainAdministratorCredential = $testAdminCredential
-                SafemodeAdministratorPassword = $testSafemodeCredential
+                Credential = $testAdminCredential
+                SafeModeAdministratorPassword = $testSafemodeCredential
             }
 
             $stubTargetResource = @{
@@ -381,12 +381,12 @@ try
                 Assert-MockCalled -CommandName Install-ADDSForest -ParameterFilter  { $DomainName -eq $testDomainName } -Scope It
             }
 
-            It 'Calls "Install-ADDSForest" with "SafemodeAdministratorPassword" when creating forest' {
-                Mock -CommandName Install-ADDSForest -ParameterFilter { $SafemodeAdministratorPassword -eq $testSafemodePassword }
+            It 'Calls "Install-ADDSForest" with "SafeModeAdministratorPassword" when creating forest' {
+                Mock -CommandName Install-ADDSForest -ParameterFilter { $SafeModeAdministratorPassword -eq $testSafemodePassword }
 
                 Set-TargetResource @newForestParams
 
-                Assert-MockCalled -CommandName Install-ADDSForest -ParameterFilter { $SafemodeAdministratorPassword -eq $testSafemodePassword } -Scope It
+                Assert-MockCalled -CommandName Install-ADDSForest -ParameterFilter { $SafeModeAdministratorPassword -eq $testSafemodePassword } -Scope It
             }
 
             It 'Calls "Install-ADDSForest" with "DnsDelegationCredential" when creating forest, if specified' {
@@ -482,12 +482,12 @@ try
                 Assert-MockCalled -CommandName Install-ADDSDomain -ParameterFilter  { $DomainType -eq 'ChildDomain' } -Scope It
             }
 
-            It 'Calls "Install-ADDSDomain" with "SafemodeAdministratorPassword" when creating child domain' {
-                Mock -CommandName Install-ADDSDomain -ParameterFilter { $SafemodeAdministratorPassword -eq $testSafemodePassword }
+            It 'Calls "Install-ADDSDomain" with "SafeModeAdministratorPassword" when creating child domain' {
+                Mock -CommandName Install-ADDSDomain -ParameterFilter { $SafeModeAdministratorPassword -eq $testSafemodePassword }
 
                 Set-TargetResource @newDomainParams
 
-                Assert-MockCalled -CommandName Install-ADDSDomain -ParameterFilter { $SafemodeAdministratorPassword -eq $testSafemodePassword } -Scope It
+                Assert-MockCalled -CommandName Install-ADDSDomain -ParameterFilter { $SafeModeAdministratorPassword -eq $testSafemodePassword } -Scope It
             }
 
             It 'Calls "Install-ADDSDomain" with "Credential" when creating child domain' {