BREAKING CHANGE: ADManagedServiceAccount: Add KerberosEncryptionType …

…Property and Refactor (dsccommunity#517) - Changes to ADManagedServiceAccount - KerberosEncryptionType property added (issue dsccommunity#511). - BREAKING CHANGE: AccountType parameter ValidateSet changed from ('Group', 'Single') to ('Group', 'Standalone') - Standalone is the correct terminology (issue dsccommunity#515). - BREAKING CHANGE: AccountType parameter default of Single removed. - Enforce positive choice of account type. - BREAKING CHANGE: MembershipAttribute parameter ValidateSet member SID changed to ObjectSid to match result property of Get-AdObject. Previous code does not work if SID is specified. - BREAKING CHANGE: AccountTypeForce parameter removed - unnecessary complication. - BREAKING CHANGE: Members parameter renamed to ManagedPasswordPrincipals - to closer match Get-AdServiceAccount result property PrincipalsAllowedToRetrieveManagedPassword. This is so that a DelegateToAccountPrincipals parameter can be added later. - Common Compare-ResourcePropertyState function used to replace function specific Compare-TargetResourceState and code refactored (issue dsccommunity#512). - Resource unit tests refactored to use nested contexts and follow the logic of the module. - Resource Integration tests added.
JohnCardenas · Nov 2, 2019 · 7df133d · 7df133d
1 parent ec8fdfb
commit 7df133d
Show file tree

Hide file tree

Showing 12 changed files with 1,854 additions and 2,070 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,12 +4,23 @@
 
 - Changes to ADServicePrincipalName
   - Added Integration testing ([issue #358](https://github.com/PowerShell/ActiveDirectoryDsc/issues/358)).
+- Changes to ADManagedServiceAccount
+  - KerberosEncryptionType property added. ([issue #511](https://github.com/PowerShell/ActiveDirectoryDsc/issues/511)).
+  - BREAKING CHANGE: AccountType parameter ValidateSet changed from ('Group', 'Single') to ('Group', 'Standalone') - Standalone is the correct terminology. Ref: [Service Accounts](https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/service-accounts).
+  ([issue #515](https://github.com/PowerShell/ActiveDirectoryDsc/issues/515)).
+  - BREAKING CHANGE: AccountType parameter default of Single removed. - Enforce positive choice of account type.
+  - BREAKING CHANGE: MembershipAttribute parameter ValidateSet member SID changed to ObjectSid to match result property of Get-AdObject. Previous code does not work if SID is specified.
+  - BREAKING CHANGE: AccountTypeForce parameter removed - unnecessary complication.
+  - BREAKING CHANGE: Members parameter renamed to ManagedPasswordPrincipals - to closer match Get-AdServiceAccount result property PrincipalsAllowedToRetrieveManagedPassword. This is so that a DelegateToAccountPrincipals parameter can be added later.
+  - Common Compare-ResourcePropertyState function used to replace function specific Compare-TargetResourceState and code refactored.
+  ([issue #512](https://github.com/PowerShell/ActiveDirectoryDsc/issues/512)).
+  - Resource unit tests refactored to use nested contexts and follow the logic of the module.
+  - Resource Integration tests added.
 
 ## 4.2.0.0
 
 - Changes to ActiveDirectoryDsc
   - Resolved custom Script Analyzer rules that was added to the test framework.
-  - Resolve style guideline violations for hashtables ([issue #516](https://github.com/PowerShell/ActiveDirectoryDsc/issues/516)).
 - Changes to ADReplicationSite
   - Added 'Description' attribute parameter ([issue #500](https://github.com/PowerShell/ActiveDirectoryDsc/issues/500)).
   - Added Integration testing ([issue #355](https://github.com/PowerShell/ActiveDirectoryDsc/issues/355)).

diff --git a/DSCResources/MSFT_ADManagedServiceAccount/MSFT_ADManagedServiceAccount.psm1 b/DSCResources/MSFT_ADManagedServiceAccount/MSFT_ADManagedServiceAccount.psm1
diff --git a/DSCResources/MSFT_ADManagedServiceAccount/MSFT_ADManagedServiceAccount.schema.mof b/DSCResources/MSFT_ADManagedServiceAccount/MSFT_ADManagedServiceAccount.schema.mof
@@ -2,16 +2,16 @@
 class MSFT_ADManagedServiceAccount : OMI_BaseResource
 {
     [Key, Description("Specifies the Security Account Manager (SAM) account name of the managed service account (ldapDisplayName 'sAMAccountName'). To be compatible with older operating systems, create a SAM account name that is 20 characters or less. Once created, the user's SamAccountName and CN cannot be changed.")] String ServiceAccountName;
-    [Write, Description("Specifies whether the user account is created or deleted. If not specified, this value defaults to Present."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
-    [Write, Description("The type of managed service account. Single will create a Single Managed Service Account (sMSA) and Group will create a Group Managed Service Account (gMSA). If not specified, this value defaults to Single."), ValueMap{"Group","Single"}, Values{"Group","Single"}] String AccountType;
-    [Write, Description("Specifies whether or not to remove the service account and recreate it when going from Single Managed Service Account to Group Managed Service Account and vice-versa. If not specified, this value defaults to $false.")] Boolean AccountTypeForce;
-    [Write, Description("Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. Specified as a Distinguished Name (DN).")] String Path;
-    [Write, Description("Specifies a description of the object (ldapDisplayName 'description').")] String Description;
-    [Write, Description("Specifies the display name of the object (ldapDisplayName 'displayName').")] String DisplayName;
-    [Write, Description("Specifies the members of the object (ldapDisplayName 'PrincipalsAllowedToRetrieveManagedPassword'). Only used when 'Group' is selected for 'AccountType'.")] String Members[];
-    [Write, Description("Active Directory attribute used to perform membership operations for Group Managed Service Accounts (gMSA). If not specified, this value defaults to SamAccountName. Only used when 'Group' is selected for 'AccountType'. Default value is 'SamAccountName'."), ValueMap{"SamAccountName","DistinguishedName","ObjectGUID","SID"}, Values{"SamAccountName","DistinguishedName","ObjectGUID","SID"}] String MembershipAttribute;
+    [Required, Description("The type of managed service account. Standalone will create a Standalone Managed Service Account (sMSA) and Group will create a Group Managed Service Account (gMSA)."), ValueMap{"Group","Standalone"}, Values{"Group","Standalone"}] String AccountType;
     [Write, Description("Specifies the user account credentials to use to perform this task. This is only required if not executing the task on a domain controller or using the parameter DomainController."), EmbeddedInstance("MSFT_Credential")] String Credential;
+    [Write, Description("Specifies the description of the account (ldapDisplayName 'description').")] String Description;
+    [Write, Description("Specifies the display name of the account (ldapDisplayName 'displayName').")] String DisplayName;
     [Write, Description("Specifies the Active Directory Domain Controller instance to use to perform the task. This is only required if not executing the task on a domain controller.")] String DomainController;
+    [Write, Description("Specifies whether the user account is created or deleted. If not specified, this value defaults to Present."), ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
+    [Write, Description("Specifies which Kerberos encryption types the account supports when creating service tickets. This value sets the encryption types supported flags of the Active Directory msDS-SupportedEncryptionTypes attribute."),ValueMap{"None","RC4","AES128","AES256"}, Values{"None","RC4","AES128","AES256"}] String KerberosEncryptionType[];
+    [Write, Description("Specifies the membership policy for systems which can use a group managed service account. (ldapDisplayName 'msDS-GroupMSAMembership'). Only used when 'Group' is selected for 'AccountType'.")] String ManagedPasswordPrincipals[];
+    [Write, Description("Active Directory attribute used to perform membership operations for Group Managed Service Accounts (gMSA). If not specified, this value defaults to SamAccountName."), ValueMap{"SamAccountName","DistinguishedName","ObjectGUID","ObjectSid"}, Values{"SamAccountName","DistinguishedName","ObjectGUID","ObjectSid"}] String MembershipAttribute;
+    [Write, Description("Specifies the X.500 path of the Organizational Unit (OU) or container where the new account is created. Specified as a Distinguished Name (DN).")] String Path;
     [Read, Description("Returns whether the user account is enabled or disabled.")] Boolean Enabled;
     [Read, Description("Returns the Distinguished Name of the Service Account.")] String DistinguishedName;
 };
diff --git a/DSCResources/MSFT_ADManagedServiceAccount/en-US/MSFT_ADManagedServiceAccount.strings.psd1 b/DSCResources/MSFT_ADManagedServiceAccount/en-US/MSFT_ADManagedServiceAccount.strings.psd1
@@ -1,16 +1,22 @@
 # culture='en-US'
 ConvertFrom-StringData @'
-    AddingManagedServiceAccount           = Adding AD Managed Service Account '{0}'. (MSA0001)
-    RemovingManagedServiceAccount         = Removing AD Managed Service Account '{0}'. (MSA0003)
-    MovingManagedServiceAccount           = Moving AD Managed Service Account '{0}' to '{1}'. (MSA0004)
-    ManagedServiceAccountNotFound         = AD Managed Service Account '{0}' was not found. (MSA0005)
-    RetrievingServiceAccount              = Retrieving AD Managed Service Account '{0}'. (MSA0006)
-    AccountTypeForceNotTrue               = The 'AccountTypeForce' was either not specified or set to false. To convert from a '{0}' MSA to a '{1}' MSA, AccountTypeForce must be set to true. (MSA0007)
-    NotDesiredPropertyState               = AD Managed Service Account '{0}' is not correct. Expected '{1}', actual '{2}'. (MSA0008)
-    MSAInDesiredState                     = AD Managed Service Account '{0}' is in the desired state. (MSA0009)
-    MSANotInDesiredState                  = AD Managed Service Account '{0}' is NOT in the desired state. (MSA0010)
-    UpdatingManagedServiceAccountProperty = Updating AD Managed Service Account property '{0}' to '{1}'. (MSA0011)
-    AddingManagedServiceAccountError      = Error adding AD Managed Service Account '{0}'. (MSA0012)
-    RetrievingPrincipalMembers            = Retrieving Principals Allowed To Retrieve Managed Password based on '{0}' property. (MSA0013)
-    RetrievingServiceAccountError         = There was an error when retrieving the AD Managed Service Account '{0}'. (MSA0014)
+    AddingManagedServiceAccountMessage            = Adding {0} Account '{1}' to '{2}'. (MSA0001)
+    RecreatingManagedServiceAccountMessage        = Recreating {0} Account '{1}'. (MSA0002)
+    RemovingManagedServiceAccountMessage          = Removing {0} Account '{1}'. (MSA0003)
+    MovingManagedServiceAccountMessage            = Moving {0} Account '{1}' from '{2}' to '{3}'. (MSA0004)
+    ManagedServiceAccountNotFoundMessage          = {0} Account '{1}' was not found. (MSA0005)
+    RetrievingManagedServiceAccountMessage        = Retrieving Account '{0}'. (MSA0006)
+    ManagedServiceAccountInDesiredStateMessage    = {0} Account '{1}' is in the desired state. (MSA0007)
+    UpdatingManagedServiceAccountPropertyMessage  = Updating {0} Account '{1}' property '{2}' to '{3}'. (MSA0008)
+    RetrievingManagedPasswordPrincipalsMessage    = Retrieving Principals Allowed To Retrieve Managed Password based on '{0}' property. (MSA0009)
+    ResourceExistsButShouldNotMessage             = {0} Account '{1}' exists but should not. (MSA0010)
+    ResourceDoesNotExistButShouldMessage          = {0} Account '{1}' does not exist but should. (MSA0011)
+    AddingManagedServiceAccountError              = Error adding {0} Account '{1}' to '{2}'. (MSA0012)
+    RemovingManagedServiceAccountError            = Error removing {0} Account '{1}'. (MSA0013)
+    SettingManagedServiceAccountError             = Error setting {0} Account '{1}'. (MSA0014)
+    MovingManagedServiceAccountError              = Error moving {0} Account '{1}' from '{2}' to '{3}'. (MSA0015)
+    RetrievingManagedServiceAccountError          = Error retrieving Account '{0}'. (MSA0016)
+    RetrievingManagedPasswordPrincipalsError      = Error retrieving Principal '{0}'. (MSA0017)
+    GettingADDomainError                          = Error getting Active Directory Domain details. (MSA0018)
+    KdsRootKeyNotFoundError                       = Error adding group account '{0}'. The KDS Root Key was not found. (MSA0019)
 '@
diff --git a/DSCResources/MSFT_ADManagedServiceAccount/en-US/about_ADManagedServiceAccount.help.txt b/DSCResources/MSFT_ADManagedServiceAccount/en-US/about_ADManagedServiceAccount.help.txt
@@ -14,48 +14,49 @@
     Key - String
     Specifies the Security Account Manager (SAM) account name of the managed service account (ldapDisplayName 'sAMAccountName'). To be compatible with older operating systems, create a SAM account name that is 20 characters or less. Once created, the user's SamAccountName and CN cannot be changed.
 
-.PARAMETER Ensure
+.PARAMETER AccountType
+    Required - String
+    Allowed values: Group, Standalone
+    The type of managed service account. Standalone will create a Standalone Managed Service Account (sMSA) and Group will create a Group Managed Service Account (gMSA).
+
+.PARAMETER Credential
     Write - String
-    Allowed values: Present, Absent
-    Specifies whether the user account is created or deleted. If not specified, this value defaults to Present.
+    Specifies the user account credentials to use to perform this task. This is only required if not executing the task on a domain controller or using the parameter DomainController.
 
-.PARAMETER AccountType
+.PARAMETER Description
     Write - String
-    Allowed values: Group, Single
-    The type of managed service account. Single will create a Single Managed Service Account (sMSA) and Group will create a Group Managed Service Account (gMSA). If not specified, this value defaults to Single.
+    Specifies the description of the account (ldapDisplayName 'description').
 
-.PARAMETER AccountTypeForce
-    Write - Boolean
-    Specifies whether or not to remove the service account and recreate it when going from Single Managed Service Account to Group Managed Service Account and vice-versa. If not specified, this value defaults to $false.
+.PARAMETER DisplayName
+    Write - String
+    Specifies the display name of the account (ldapDisplayName 'displayName').
 
-.PARAMETER Path
+.PARAMETER DomainController
     Write - String
-    Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. Specified as a Distinguished Name (DN).
+    Specifies the Active Directory Domain Controller instance to use to perform the task. This is only required if not executing the task on a domain controller.
 
-.PARAMETER Description
+.PARAMETER Ensure
     Write - String
-    Specifies a description of the object (ldapDisplayName 'description').
+    Allowed values: Present, Absent
+    Specifies whether the user account is created or deleted. If not specified, this value defaults to Present.
 
-.PARAMETER DisplayName
+.PARAMETER KerberosEncryptionType
     Write - String
-    Specifies the display name of the object (ldapDisplayName 'displayName').
+    Allowed values: None, RC4, AES128, AES256
+    Specifies which Kerberos encryption types the account supports when creating service tickets. This value sets the encryption types supported flags of the Active Directory msDS-SupportedEncryptionTypes attribute.
 
-.PARAMETER Members
+.PARAMETER ManagedPasswordPrincipals
     Write - String
-    Specifies the members of the object (ldapDisplayName 'PrincipalsAllowedToRetrieveManagedPassword'). Only used when 'Group' is selected for 'AccountType'.
+    Specifies the membership policy for systems which can use a group managed service account. (ldapDisplayName 'msDS-GroupMSAMembership'). Only used when 'Group' is selected for 'AccountType'.
 
 .PARAMETER MembershipAttribute
     Write - String
     Allowed values: SamAccountName, DistinguishedName, ObjectGUID, SID
-    Active Directory attribute used to perform membership operations for Group Managed Service Accounts (gMSA). If not specified, this value defaults to SamAccountName. Only used when 'Group' is selected for 'AccountType'. Default value is 'SamAccountName'.
+    Active Directory attribute used to perform membership operations for Group Managed Service Accounts (gMSA). If not specified, this value defaults to SamAccountName.
 
-.PARAMETER Credential
-    Write - String
-    Specifies the user account credentials to use to perform this task. This is only required if not executing the task on a domain controller or using the parameter DomainController.
-
-.PARAMETER DomainController
+.PARAMETER Path
     Write - String
-    Specifies the Active Directory Domain Controller instance to use to perform the task. This is only required if not executing the task on a domain controller.
+    Specifies the X.500 path of the Organizational Unit (OU) or container where the new account is created. Specified as a Distinguished Name (DN).
 
 .PARAMETER Enabled
     Read - Boolean
@@ -67,18 +68,19 @@
 
 .EXAMPLE 1
 
-This configuration will create a managed service account.
+This configuration will create a standalone managed service account.
 
 Configuration ADManagedServiceAccount_CreateManagedServiceAccount_Config
 {
     Import-DscResource -Module ActiveDirectoryDsc
 
     Node localhost
     {
-        ADManagedServiceAccount 'ExampleSingleMSA'
+        ADManagedServiceAccount 'ExampleStandaloneMSA'
         {
             Ensure             = 'Present'
             ServiceAccountName = 'Service01'
+            AccountType        = 'Standalone'
         }
     }
 }
@@ -98,7 +100,6 @@ Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccount_Config
             Ensure             = 'Present'
             ServiceAccountName = 'Service01'
             AccountType        = 'Group'
-            Path               = 'OU=ServiceAccounts,DC=contoso,DC=com'
         }
     }
 }
@@ -118,7 +119,6 @@ Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccountWithMember
             Ensure             = 'Present'
             ServiceAccountName = 'Service01'
             AccountType        = 'Group'
-            Path               = 'OU=ServiceAccounts,DC=contoso,DC=com'
             Members            = 'User01', 'Computer01$'
         }
 
@@ -127,7 +127,6 @@ Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccountWithMember
             Ensure             = 'Present'
             ServiceAccountName = 'Service02'
             AccountType        = 'Group'
-            Path               = 'OU=ServiceAccounts,DC=contoso,DC=com'
             Members            = 'CN=User01,OU=Users,DC=contoso,DC=com', 'CN=Computer01,OU=Computers,DC=contoso,DC=com'
         }
     }

diff --git a/.../ADManagedServiceAccount/1-ADManagedServiceAccount_CreateManagedServiceAccount_Config.ps1 b/.../ADManagedServiceAccount/1-ADManagedServiceAccount_CreateManagedServiceAccount_Config.ps1
@@ -19,18 +19,20 @@
 
 <#
     .DESCRIPTION
-        This configuration will create a managed service account.
+        This configuration will create a standalone managed service account in the default 'Managed Service Accounts'
+        container.
 #>
 Configuration ADManagedServiceAccount_CreateManagedServiceAccount_Config
 {
     Import-DscResource -Module ActiveDirectoryDsc
 
     Node localhost
     {
-        ADManagedServiceAccount 'ExampleSingleMSA'
+        ADManagedServiceAccount 'ExampleStandaloneMSA'
         {
             Ensure             = 'Present'
             ServiceAccountName = 'Service01'
+            AccountType        = 'Standalone'
         }
     }
 }
diff --git a/...nagedServiceAccount/2-ADManagedServiceAccount_CreateGroupManagedServiceAccount_Config.ps1 b/...nagedServiceAccount/2-ADManagedServiceAccount_CreateGroupManagedServiceAccount_Config.ps1
@@ -19,7 +19,8 @@
 
 <#
     .DESCRIPTION
-        This configuration will create a group managed service account.
+        This configuration will create a group managed service account in the default 'Managed Service Accounts'
+        container.
 #>
 Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccount_Config
 {
@@ -32,7 +33,6 @@ Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccount_Config
             Ensure             = 'Present'
             ServiceAccountName = 'Service01'
             AccountType        = 'Group'
-            Path               = 'OU=ServiceAccounts,DC=contoso,DC=com'
         }
     }
 }
diff --git a/...eAccount/3-ADManagedServiceAccount_CreateGroupManagedServiceAccountWithMembers_Config.ps1 b/...eAccount/3-ADManagedServiceAccount_CreateGroupManagedServiceAccountWithMembers_Config.ps1
@@ -19,7 +19,8 @@
 
 <#
     .DESCRIPTION
-        This configuration will create a group managed service account with members.
+        This configuration will create a group managed service account with members in the default 'Managed Service
+        Accounts' container.
 #>
 Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccountWithMembers_Config
 {
@@ -29,20 +30,18 @@ Configuration ADManagedServiceAccount_CreateGroupManagedServiceAccountWithMember
     {
         ADManagedServiceAccount 'AddingMembersUsingSamAccountName'
         {
-            Ensure             = 'Present'
-            ServiceAccountName = 'Service01'
-            AccountType        = 'Group'
-            Path               = 'OU=ServiceAccounts,DC=contoso,DC=com'
-            Members            = 'User01', 'Computer01$'
+            Ensure                    = 'Present'
+            ServiceAccountName        = 'Service01'
+            AccountType               = 'Group'
+            ManagedPasswordPrincipals = 'User01', 'Computer01$'
         }
 
         ADManagedServiceAccount 'AddingMembersUsingDN'
         {
-            Ensure             = 'Present'
-            ServiceAccountName = 'Service02'
-            AccountType        = 'Group'
-            Path               = 'OU=ServiceAccounts,DC=contoso,DC=com'
-            Members            = 'CN=User01,OU=Users,DC=contoso,DC=com', 'CN=Computer01,OU=Computers,DC=contoso,DC=com'
+            Ensure                    = 'Present'
+            ServiceAccountName        = 'Service02'
+            AccountType               = 'Group'
+            ManagedPasswordPrincipals = 'CN=User01,OU=Users,DC=contoso,DC=com', 'CN=Computer01,OU=Computers,DC=contoso,DC=com'
         }
     }
 }