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 · ce2b5d5 · ce2b5d5
1 parent 3536b88
commit ce2b5d5
Show file tree

Hide file tree

Showing 9 changed files with 137 additions and 93 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/DSCResources/MSFT_ADDomain/en-US/about_ADDomain.help.txt b/DSCResources/MSFT_ADDomain/en-US/about_ADDomain.help.txt
@@ -12,9 +12,9 @@
     Key - String
     The fully qualified domain name (FQDN) of the new domain.
 
-.PARAMETER DomainAdministratorCredential
+.PARAMETER Credential
     Required - String
-    Credentials used to query for domain existence.
+    Specifies the user name and password that corresponds to the account used to install the domain controller.
 
 .PARAMETER SafemodeAdministratorPassword
     Required - String
@@ -66,7 +66,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
@@ -89,8 +94,8 @@ Configuration NewForest_Config
         ADDomain $Node.DomainName
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $DomainAdministratorCredential
-            SafemodeAdministratorPassword = $DomainAdministratorCredential
+            Credential                    = $Credential
+            SafemodeAdministratorPassword = $SafeModePassword
             ForestMode                    = $Node.FFL
         }
     }
@@ -118,7 +123,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
@@ -141,8 +151,8 @@ Configuration NewChildDomain_Config
         ADDomain $Node.DomainName
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $DomainAdministratorCredential
-            SafemodeAdministratorPassword = $DomainAdministratorCredential
+            Credential                    = $Credential
+            SafemodeAdministratorPassword = $SafeModePassword
             DomainMode                    = $Node.DFL
             ParentDomainName              = $node.ParentDomain
         }
@@ -170,20 +180,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
@@ -199,28 +211,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'
         }
 
@@ -237,18 +252,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'
         }
     }
@@ -291,20 +308,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
@@ -320,16 +339,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'
@@ -338,9 +357,9 @@ Configuration NewDomainWithTwoDCs_Config
         ADUser 'FirstUser'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domainCred
+            DomainAdministratorCredential = $Credential
             UserName                      = 'dummy'
-            Password                      = $NewADUserCred
+            Password                      = $NewADUserPassword
             Ensure                        = 'Present'
             DependsOn                     = '[WaitForADDomain]DscForestWait'
         }
@@ -357,7 +376,7 @@ Configuration NewDomainWithTwoDCs_Config
         WaitForADDomain 'DscForestWait'
         {
             DomainName           = $Node.DomainName
-            DomainUserCredential = $domainCred
+            DomainUserCredential = $Credential
             RetryCount           = $Node.RetryCount
             RetryIntervalSec     = $Node.RetryIntervalSec
             DependsOn            = '[WindowsFeature]ADDSInstall'
@@ -366,8 +385,8 @@ Configuration NewDomainWithTwoDCs_Config
         ADDomainController 'SecondDC'
         {
             DomainName                    = $Node.DomainName
-            DomainAdministratorCredential = $domainCred
-            SafemodeAdministratorPassword = $SafemodeAdministratorCred
+            DomainAdministratorCredential = $Credential
+            SafeModeAdministratorPassword = $SafeModePassword
             DependsOn                     = '[WaitForADDomain]DscForestWait'
         }
     }

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
         }