Changes to ADDomainTrust

- BREAKING CHANGE: Renamed the parameter `TargetDomainAdministratorCredential` to `TargetCredential` 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 · a51b734 · a51b734
1 parent 18b6b9e
commit a51b734
Show file tree

Hide file tree

Showing 8 changed files with 93 additions and 90 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -89,6 +89,9 @@
   - Minor change to the unit tests that did not correct assert the localized
     string when an account is not found.
 - Changes to ADDomainTrust
+  - BREAKING CHANGE: Renamed the parameter `TargetDomainAdministratorCredential`
+    to `TargetCredential` 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)).
   - Refactored the resource to enable unit tests, and at the same time changed
     it to use the same code pattern as the resource xADObjectEnabledState.
   - Added unit tests ([issue #324](https://github.com/PowerShell/ActiveDirectoryDsc/issues/324)).

diff --git a/DSCResources/MSFT_ADDomainTrust/MSFT_ADDomainTrust.psm1 b/DSCResources/MSFT_ADDomainTrust/MSFT_ADDomainTrust.psm1
@@ -17,7 +17,7 @@ $script:localizedData = Get-LocalizedData -ResourceName 'MSFT_ADDomainTrust'
     .PARAMETER TargetDomainName
         Specifies the name of the Active Directory domain that is being trusted.
 
-    .PARAMETER TargetDomainAdministratorCredential
+    .PARAMETER TargetCredential
         Specifies the credentials to authenticate to the target domain.
 
     .PARAMETER TrustType
@@ -43,7 +43,7 @@ function Get-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $TargetDomainAdministratorCredential,
+        $TargetCredential,
 
         [Parameter(Mandatory = $true)]
         [ValidateSet('External', 'Forest')]
@@ -57,19 +57,19 @@ function Get-TargetResource
     )
 
     # Return a credential object without the password.
-    $cimCredentialInstance = New-CimCredentialInstance -Credential $TargetDomainAdministratorCredential
+    $cimCredentialInstance = New-CimCredentialInstance -Credential $TargetCredential
 
     $returnValue = @{
-        SourceDomainName                    = $SourceDomainName
-        TargetDomainName                    = $TargetDomainName
-        TargetDomainAdministratorCredential = $cimCredentialInstance
+        SourceDomainName = $SourceDomainName
+        TargetDomainName = $TargetDomainName
+        TargetCredential = $cimCredentialInstance
     }
 
     $getTrustTargetAndSourceObject = @{
-        SourceDomainName                    = $SourceDomainName
-        TargetDomainName                    = $TargetDomainName
-        TargetDomainAdministratorCredential = $TargetDomainAdministratorCredential
-        TrustType                           = $TrustType
+        SourceDomainName = $SourceDomainName
+        TargetDomainName = $TargetDomainName
+        TargetCredential = $TargetCredential
+        TrustType        = $TrustType
     }
 
     $trustSource, $trustTarget = Get-TrustSourceAndTargetObject @getTrustTargetAndSourceObject
@@ -114,7 +114,7 @@ function Get-TargetResource
     .PARAMETER TargetDomainName
         Specifies the name of the Active Directory domain that is being trusted.
 
-    .PARAMETER TargetDomainAdministratorCredential
+    .PARAMETER TargetCredential
         Specifies the credentials to authenticate to the target domain.
 
     .PARAMETER TrustType
@@ -143,7 +143,7 @@ function Set-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $TargetDomainAdministratorCredential,
+        $TargetCredential,
 
         [Parameter(Mandatory = $true)]
         [ValidateSet('External', 'Forest')]
@@ -162,10 +162,10 @@ function Set-TargetResource
     )
 
     $getTrustTargetAndSourceObject = @{
-        SourceDomainName                    = $SourceDomainName
-        TargetDomainName                    = $TargetDomainName
-        TargetDomainAdministratorCredential = $TargetDomainAdministratorCredential
-        TrustType                           = $TrustType
+        SourceDomainName = $SourceDomainName
+        TargetDomainName = $TargetDomainName
+        TargetCredential = $TargetCredential
+        TrustType        = $TrustType
     }
 
     $trustSource, $trustTarget = Get-TrustSourceAndTargetObject @getTrustTargetAndSourceObject
@@ -283,7 +283,7 @@ function Set-TargetResource
     .PARAMETER TargetDomainName
         Specifies the name of the Active Directory domain that is being trusted.
 
-    .PARAMETER TargetDomainAdministratorCredential
+    .PARAMETER TargetCredential
         Specifies the credentials to authenticate to the target domain.
 
     .PARAMETER TrustType
@@ -313,7 +313,7 @@ function Test-TargetResource
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $TargetDomainAdministratorCredential,
+        $TargetCredential,
 
         [Parameter(Mandatory = $true)]
         [ValidateSet('External', 'Forest')]
@@ -369,7 +369,7 @@ function Test-TargetResource
     .PARAMETER TargetDomainName
         Specifies the name of the Active Directory domain that is being trusted.
 
-    .PARAMETER TargetDomainAdministratorCredential
+    .PARAMETER TargetCredential
         Specifies the credentials to authenticate to the target domain.
 
     .PARAMETER TrustType
@@ -398,7 +398,7 @@ function Compare-TargetResourceState
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $TargetDomainAdministratorCredential,
+        $TargetCredential,
 
         [Parameter(Mandatory = $true)]
         [ValidateSet('External', 'Forest')]
@@ -417,11 +417,11 @@ function Compare-TargetResourceState
     )
 
     $getTargetResourceParameters = @{
-        SourceDomainName                    = $SourceDomainName
-        TargetDomainName                    = $TargetDomainName
-        TargetDomainAdministratorCredential = $TargetDomainAdministratorCredential
-        TrustType                           = $TrustType
-        TrustDirection                      = $TrustDirection
+        SourceDomainName = $SourceDomainName
+        TargetDomainName = $TargetDomainName
+        TargetCredential = $TargetCredential
+        TrustType        = $TrustType
+        TrustDirection   = $TrustDirection
     }
 
     $getTargetResourceResult = Get-TargetResource @getTargetResourceParameters
@@ -604,7 +604,7 @@ function ConvertFrom-DirectoryContextType
     .PARAMETER TargetDomainName
         Specifies the name of the Active Directory domain that is being trusted.
 
-    .PARAMETER TargetDomainAdministratorCredential
+    .PARAMETER TargetCredential
         Specifies the credentials to authenticate to the target domain.
 
     .PARAMETER TrustType
@@ -632,7 +632,7 @@ function Get-TrustSourceAndTargetObject
 
         [Parameter(Mandatory = $true)]
         [System.Management.Automation.PSCredential]
-        $TargetDomainAdministratorCredential,
+        $TargetCredential,
 
         [Parameter(Mandatory = $true)]
         [ValidateSet('External', 'Forest')]
@@ -646,7 +646,7 @@ function Get-TrustSourceAndTargetObject
     $getADDirectoryContextParameters = @{
         DirectoryContextType = $directoryContextType
         Name                 = $TargetDomainName
-        Credential           = $TargetDomainAdministratorCredential
+        Credential           = $TargetCredential
     }
 
     $targetDirectoryContext = Get-ADDirectoryContext @getADDirectoryContextParameters

diff --git a/DSCResources/MSFT_ADDomainTrust/MSFT_ADDomainTrust.schema.mof b/DSCResources/MSFT_ADDomainTrust/MSFT_ADDomainTrust.schema.mof
@@ -2,7 +2,7 @@
 class MSFT_ADDomainTrust : OMI_BaseResource
 {
     [Write, Description("Specifies whether the computer account is present or absent. Default value is 'Present'."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
-    [Required, Description("Specifies the credentials to authenticate to the target domain."), EmbeddedInstance("MSFT_Credential")] String TargetDomainAdministratorCredential;
+    [Required, Description("Specifies the credentials to authenticate to the target domain."), EmbeddedInstance("MSFT_Credential")] String TargetCredential;
     [Key, Description("Specifies the name of the Active Directory domain that is being trusted.")] String TargetDomainName;
     [Required, Description("Specifies the type of trust. The value 'External' means the context Domain, while the value 'Forest' means the context 'Forest'."), ValueMap{"External","Forest"}, Values{"External","Forest"}] String TrustType;
     [Required, Description("Specifies the direction of the trust."), ValueMap{"Bidirectional","Inbound","Outbound"}, Values{"Bidirectional","Inbound","Outbound"}] String TrustDirection;

diff --git a/DSCResources/MSFT_ADDomainTrust/en-US/about_ADDomainTrust.help.txt b/DSCResources/MSFT_ADDomainTrust/en-US/about_ADDomainTrust.help.txt
@@ -13,7 +13,7 @@
     Allowed values: Present, Absent
     Specifies whether the computer account is present or absent. Default value is 'Present'.
 
-.PARAMETER TargetDomainAdministratorCredential
+.PARAMETER TargetCredential
     Required - String
     Specifies the credentials to authenticate to the target domain.
 
@@ -63,12 +63,12 @@ Configuration ADDomainTrust_NewOneWayTrust_Config
     {
         ADDomainTrust 'Trust'
         {
-            Ensure                              = 'Present'
-            SourceDomainName                    = $SourceDomain
-            TargetDomainName                    = $TargetDomain
-            TargetDomainAdministratorCredential = $TargetDomainAdminCred
-            TrustDirection                      = 'Inbound'
-            TrustType                           = 'External'
+            Ensure           = 'Present'
+            SourceDomainName = $SourceDomain
+            TargetDomainName = $TargetDomain
+            TargetCredential = $TargetDomainAdminCred
+            TrustDirection   = 'Inbound'
+            TrustType        = 'External'
         }
     }
 }

diff --git a/Examples/Resources/ADDomainTrust/1-ADDomainTrust_NewOneWayTrust_Config.ps1 b/Examples/Resources/ADDomainTrust/1-ADDomainTrust_NewOneWayTrust_Config.ps1
@@ -45,12 +45,12 @@ Configuration ADDomainTrust_NewOneWayTrust_Config
     {
         ADDomainTrust 'Trust'
         {
-            Ensure                              = 'Present'
-            SourceDomainName                    = $SourceDomain
-            TargetDomainName                    = $TargetDomain
-            TargetDomainAdministratorCredential = $TargetDomainAdminCred
-            TrustDirection                      = 'Inbound'
-            TrustType                           = 'External'
+            Ensure           = 'Present'
+            SourceDomainName = $SourceDomain
+            TargetDomainName = $TargetDomain
+            TargetCredential = $TargetDomainAdminCred
+            TrustDirection   = 'Inbound'
+            TrustType        = 'External'
         }
     }
 }
diff --git a/Tests/Integration/MSFT_ADDomainTrust.Integration.Tests.ps1 b/Tests/Integration/MSFT_ADDomainTrust.Integration.Tests.ps1
@@ -75,7 +75,7 @@ try
                 $resourceCurrentState.Ensure | Should -Be 'Present'
                 $resourceCurrentState.SourceDomainName | Should -Be $configurationData.AllNodes.SourceDomain
                 $resourceCurrentState.TargetDomainName | Should -Be $configurationData.AllNodes.TargetDomain
-                $resourceCurrentState.TargetDomainAdministratorCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
+                $resourceCurrentState.TargetCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
                 $resourceCurrentState.TrustType | Should -Be 'External'
                 $resourceCurrentState.TrustDirection | Should -Be 'Outbound'
             }
@@ -126,7 +126,7 @@ try
                 $resourceCurrentState.Ensure | Should -Be 'Present'
                 $resourceCurrentState.SourceDomainName | Should -Be $configurationData.AllNodes.SourceDomain
                 $resourceCurrentState.TargetDomainName | Should -Be $configurationData.AllNodes.TargetDomain
-                $resourceCurrentState.TargetDomainAdministratorCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
+                $resourceCurrentState.TargetCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
                 $resourceCurrentState.TrustType | Should -Be 'External'
                 $resourceCurrentState.TrustDirection | Should -Be 'Inbound'
             }
@@ -177,7 +177,7 @@ try
                 $resourceCurrentState.Ensure | Should -Be 'Absent'
                 $resourceCurrentState.SourceDomainName | Should -Be $configurationData.AllNodes.SourceDomain
                 $resourceCurrentState.TargetDomainName | Should -Be $configurationData.AllNodes.TargetDomain
-                $resourceCurrentState.TargetDomainAdministratorCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
+                $resourceCurrentState.TargetCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
                 $resourceCurrentState.TrustType | Should -BeNullOrEmpty
                 $resourceCurrentState.TrustDirection | Should -BeNullOrEmpty
             }
@@ -228,7 +228,7 @@ try
                 $resourceCurrentState.Ensure | Should -Be 'Present'
                 $resourceCurrentState.SourceDomainName | Should -Be $configurationData.AllNodes.SourceForest
                 $resourceCurrentState.TargetDomainName | Should -Be $configurationData.AllNodes.TargetForest
-                $resourceCurrentState.TargetDomainAdministratorCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
+                $resourceCurrentState.TargetCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
                 $resourceCurrentState.TrustType | Should -Be 'Forest'
                 $resourceCurrentState.TrustDirection | Should -Be 'Outbound'
             }
@@ -279,7 +279,7 @@ try
                 $resourceCurrentState.Ensure | Should -Be 'Present'
                 $resourceCurrentState.SourceDomainName | Should -Be $configurationData.AllNodes.SourceForest
                 $resourceCurrentState.TargetDomainName | Should -Be $configurationData.AllNodes.TargetForest
-                $resourceCurrentState.TargetDomainAdministratorCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
+                $resourceCurrentState.TargetCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
                 $resourceCurrentState.TrustType | Should -Be 'Forest'
                 $resourceCurrentState.TrustDirection | Should -Be 'Inbound'
             }
@@ -330,7 +330,7 @@ try
                 $resourceCurrentState.Ensure | Should -Be 'Absent'
                 $resourceCurrentState.SourceDomainName | Should -Be $configurationData.AllNodes.SourceForest
                 $resourceCurrentState.TargetDomainName | Should -Be $configurationData.AllNodes.TargetForest
-                $resourceCurrentState.TargetDomainAdministratorCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
+                $resourceCurrentState.TargetCredential.UserName | Should -Be $configurationData.AllNodes.TargetUserName
                 $resourceCurrentState.TrustType | Should -BeNullOrEmpty
                 $resourceCurrentState.TrustDirection | Should -BeNullOrEmpty
             }

diff --git a/Tests/Integration/MSFT_ADDomainTrust.config.ps1 b/Tests/Integration/MSFT_ADDomainTrust.config.ps1
@@ -59,11 +59,11 @@ Configuration MSFT_ADDomainTrust_CreateDomainTrust_Config
     {
         ADDomainTrust 'Integration_Test'
         {
-            SourceDomainName                    = $Node.SourceDomain
-            TargetDomainName                    = $Node.TargetDomain
-            TrustType                           = 'External'
-            TrustDirection                      = 'Outbound'
-            TargetDomainAdministratorCredential = New-Object `
+            SourceDomainName = $Node.SourceDomain
+            TargetDomainName = $Node.TargetDomain
+            TrustType        = 'External'
+            TrustDirection   = 'Outbound'
+            TargetCredential = New-Object `
                 -TypeName System.Management.Automation.PSCredential `
                 -ArgumentList @($Node.TargetUserName, (ConvertTo-SecureString -String $Node.TargetPassword -AsPlainText -Force))
 
@@ -83,11 +83,11 @@ Configuration MSFT_ADDomainTrust_ChangeDomainTrustDirection_Config
     {
         ADDomainTrust 'Integration_Test'
         {
-            SourceDomainName                    = $Node.SourceDomain
-            TargetDomainName                    = $Node.TargetDomain
-            TrustType                           = 'External'
-            TrustDirection                      = 'Inbound'
-            TargetDomainAdministratorCredential = New-Object `
+            SourceDomainName = $Node.SourceDomain
+            TargetDomainName = $Node.TargetDomain
+            TrustType        = 'External'
+            TrustDirection   = 'Inbound'
+            TargetCredential = New-Object `
                 -TypeName System.Management.Automation.PSCredential `
                 -ArgumentList @($Node.TargetUserName, (ConvertTo-SecureString -String $Node.TargetPassword -AsPlainText -Force))
 
@@ -107,12 +107,12 @@ Configuration MSFT_ADDomainTrust_RemoveDomainTrust_Config
     {
         ADDomainTrust 'Integration_Test'
         {
-            Ensure                              = 'Absent'
-            SourceDomainName                    = $Node.SourceDomain
-            TargetDomainName                    = $Node.TargetDomain
-            TrustType                           = 'External'
-            TrustDirection                      = 'Bidirectional'
-            TargetDomainAdministratorCredential = New-Object `
+            Ensure           = 'Absent'
+            SourceDomainName = $Node.SourceDomain
+            TargetDomainName = $Node.TargetDomain
+            TrustType        = 'External'
+            TrustDirection   = 'Bidirectional'
+            TargetCredential = New-Object `
                 -TypeName System.Management.Automation.PSCredential `
                 -ArgumentList @($Node.TargetUserName, (ConvertTo-SecureString -String $Node.TargetPassword -AsPlainText -Force))
 
@@ -132,11 +132,11 @@ Configuration MSFT_ADDomainTrust_CreateForestTrust_Config
     {
         ADDomainTrust 'Integration_Test'
         {
-            SourceDomainName                    = $Node.SourceForest
-            TargetDomainName                    = $Node.TargetForest
-            TrustType                           = 'Forest'
-            TrustDirection                      = 'Outbound'
-            TargetDomainAdministratorCredential = New-Object `
+            SourceDomainName = $Node.SourceForest
+            TargetDomainName = $Node.TargetForest
+            TrustType        = 'Forest'
+            TrustDirection   = 'Outbound'
+            TargetCredential = New-Object `
                 -TypeName System.Management.Automation.PSCredential `
                 -ArgumentList @($Node.TargetUserName, (ConvertTo-SecureString -String $Node.TargetPassword -AsPlainText -Force))
 
@@ -156,11 +156,11 @@ Configuration MSFT_ADDomainTrust_ChangeForestTrustDirection_Config
     {
         ADDomainTrust 'Integration_Test'
         {
-            SourceDomainName                    = $Node.SourceForest
-            TargetDomainName                    = $Node.TargetForest
-            TrustType                           = 'Forest'
-            TrustDirection                      = 'Inbound'
-            TargetDomainAdministratorCredential = New-Object `
+            SourceDomainName = $Node.SourceForest
+            TargetDomainName = $Node.TargetForest
+            TrustType        = 'Forest'
+            TrustDirection   = 'Inbound'
+            TargetCredential = New-Object `
                 -TypeName System.Management.Automation.PSCredential `
                 -ArgumentList @($Node.TargetUserName, (ConvertTo-SecureString -String $Node.TargetPassword -AsPlainText -Force))
 
@@ -180,12 +180,12 @@ Configuration MSFT_ADDomainTrust_RemoveForestTrust_Config
     {
         ADDomainTrust 'Integration_Test'
         {
-            Ensure                              = 'Absent'
-            SourceDomainName                    = $Node.SourceForest
-            TargetDomainName                    = $Node.TargetForest
-            TrustType                           = 'Forest'
-            TrustDirection                      = 'Bidirectional'
-            TargetDomainAdministratorCredential = New-Object `
+            Ensure           = 'Absent'
+            SourceDomainName = $Node.SourceForest
+            TargetDomainName = $Node.TargetForest
+            TrustType        = 'Forest'
+            TrustDirection   = 'Bidirectional'
+            TargetCredential = New-Object `
                 -TypeName System.Management.Automation.PSCredential `
                 -ArgumentList @($Node.TargetUserName, (ConvertTo-SecureString -String $Node.TargetPassword -AsPlainText -Force))