AddsDomainPrincipals.adoc

DSC Resource 'AddsDomainPrincipals'

AddsDomainPrincipals manages Users and Managed Service Accounts within Active Directory.

Source	https://github.com/dsccommunity/CommonTasks/tree/main/source/DSCResources/AddsDomainPrincipals
DSC Resource	ActiveDirectoryDsc
Documentation	ADComputer, ADUser, ADManagedServiceAccount, ADKDSKey

Table 1. Attributes of category 'AddsDomainPrincipals'

Parameter	Attribute	DataType	Description	Allowed Values
DomainDn		String	Distinguished Name (DN) of the domain.
Computers		Hashtable[]	List of computer accounts to create.
Users		Hashtable[]	List of users to create.
KDSKey		Hashtable	Management of KDS Root Keys within Active Directory. The KDS root keys are used to begin generating Group Managed Service Account (gMSA) passwords. KDSKey uses a localized date and shall be proceed after setting the timezone (ComputerSettings) otherwise two keys are be created.
ManagedServiceAccounts		Hashtable[]	List of managed service accounts to create.

Table 2. Selected Attributes of category 'AddsDomainPrincipals/Computers'

Parameter	Attribute	DataType	Description	Allowed Values
ComputerName	Key	String	Specifies the name of the Active Directory computer account to manage. You can identify a computer by its distinguished name, GUID, security identifier (SID) or Security Accounts Manager (SAM) account name.
Location		String	Specifies the location of the computer, such as an office number.
DnsHostName		String	Specifies the fully qualified domain name (FQDN) of the computer account.
ServicePrincipalNames		String[]	Specifies the service principal names for the computer account.
UserPrincipalName		String	Specifies the User Principal Name (UPN) assigned to the computer account.
DisplayName		String	Specifies the display name of the computer account.
Path		String	Specifies the X.500 path of the Organizational Unit (OU) or container where the computer is located.
Description		String	Specifies a description of the computer account.
Manager		String	Specifies the user or group Distinguished Name that manages the computer account. Valid values are the user’s or group’s DistinguishedName, ObjectGUID, SID or SamAccountName.
DomainController		String	Specifies the Active Directory Domain Services instance to connect to perform the task.
Credential		PSCredential	Specifies the user account credentials to use to perform the task.
RequestFile		String	Specifies the full path to the Offline Domain Join Request file to create.
Ensure		String	Specifies whether the computer account is present or absent.	Present (default) Absent
RestoreFromRecycleBin		Boolean	Try to restore the computer account from the recycle bin before creating a new one.
EnabledOnCreation		Boolean	Specifies if the computer account is created enabled or disabled. By default the Enabled property of the computer account will be set to the default value of the cmdlet New-ADComputer. This property is ignored if the parameter RequestFile is specified in the same configuration. This parameter does not enforce the property Enabled. To enforce the property Enabled see the resource ADObjectEnabledState.
MemberOf		String[]	List of Domain Groups of the computer. Only domain groups of the member domain are supported.

Table 3. Selected Attributes of category 'AddsDomainPrincipals/Users' - see ADUser for more attributes

Parameter	Attribute	DataType	Description	Allowed Values
DomainName	Key	String	Name of the domain where the user account is located (only used if password is managed).	Default: DomainDn
UserName	Key	String	Specifies the Security Account Manager (SAM) account name of the user (ldapDisplayName 'sAMAccountName').
Password		PSCredential	Specifies a new password value for the account.
Ensure		String	Specifies whether the user account should be present or absent.	Present (default) Absent
CommonName		String	Specifies the common name assigned to the user account (ldapDisplayName 'cn'). If not specified the default value will be the same value provided in parameter UserName.
DisplayName		String	Specifies the display name of the object (ldapDisplayName 'displayName').
UserPrincipalName		String	Specifies the User Principal Name (UPN) assigned to the user account (ldapDisplayName 'userPrincipalName').
MemberOf		String[]	List of Domain Groups of the user. Only domain groups of the member domain are supported.

Table 4. Selected Attributes of category 'AddsDomainPrincipals/KDSKey'

Parameter	Attribute	DataType	Description	Allowed Values
EffectiveTime	Key	String	Specifies the Effective time when a KDS root key can be used. There is a 10 hour minimum from creation date to allow active directory to properly replicate across all domain controllers. For this reason, the date must be set in the future for creation. While this parameter accepts a string, it will be converted into a DateTime object. This will also try to take into account cultural settings.
Ensure		String	Specifies if this KDS Root Key should be present or absent.	Present (default)
AllowUnsafeEffectiveTime		Boolean	This option will allow you to create a KDS root key if EffectiveTime is set in the past. This may cause issues if you are creating a Group Managed Service Account right after you create the KDS Root Key. In order to get around this, you must create the KDS Root Key using a date in the past. This should be used at your own risk and should only be used in lab environments.
ForceRemove		Boolean	This option will allow you to remove a KDS root key if there is only one key left. It should not break your Group Managed Service Accounts (gMSA), but if the gMSA password expires and it needs to request a new password, it will not be able to generate a new password until a new KDS Root Key is installed and ready for use. Because of this, the last KDS Root Key will not be removed unless this option is specified.

Table 5. Selected Attributes of category 'AddsDomainPrincipals/ManagedServiceAccounts'

Parameter	Attribute	DataType	Description	Allowed Values
ServiceAccountName	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.
AccountType	Mandatory	String	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).	Group Standalone
Credential		PSCredential	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.
Description		String	Specifies the description of the account (ldapDisplayName description).
DisplayName		String	Specifies the display name of the account (ldapDisplayName displayName).
DomainController		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.
Ensure		String	Specifies whether the user account is created or deleted.	Present (default) Absent
KerberosEncryptionType		String[]	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.	None RC4 AES128 AES256
ManagedPasswordPrincipals		String[]	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.
Computer		String	Specifies the Active Directory computer that will host the service account. You can identify a computer by its distinguished name, GUID, security identifier (SID) or Security Accounts Manager (SAM) account name. Only used when Standalone is selected for AccountType.
MembershipAttribute		String	Active Directory attribute used to perform membership operations for Group Managed Service Accounts (gMSA).	SamAccountName (default) DistinguishedName ObjectGUID ObjectSid
Path		String	Specifies the X.500 path of the Organizational Unit (OU) or container where the new account is created. Specified as a Distinguished Name (DN).
MemberOf		String[]	List of Domain Groups of the managed service account. Only domain groups of the member domain are supported.

Example

AddsDomainPrincipals:
  DomainDN: DC=contoso,DC=com
  Computers:
    - ComputerName: Server01
      Description:  Testserver 1
      Path:        'OU=Servers,OU=Computers,DC=contoso,DC=com'
    - ComputerName: Client01
      EnabledOnCreation: false
      Description: Testclient 1
      Path:        'OU=Clients,OU=Computers,DC=contoso,DC=com'
      MemberOf:
        - Client Security Group
  Users:
    - UserName: test1
      Password: '[ENC=PE9ianM...=]'
      MemberOf:
        - Domain Users
    - UserName: test2
      Password: '[ENC=PE9ianM...=]'
      MemberOf:
        - Domain Admins
        - Domain Users

  KDSKey:
    EffectiveTime:            '1-jan-2021 00:00'
    AllowUnsafeEffectiveTime: true   # Use with caution

  ManagedServiceAccounts:
    - ServiceAccountName: ServiceLocal
      AccountType:        Standalone
      Computer:           Client01
      MemberOf:
        - Service Users
    - ServiceAccountName: ServiceGroup
      AccountType:        Group
      Path:               'OU=ServiceAccounts,DC=contoso,DC=com'
      ManagedPasswordPrincipals:
        - User01
        - Server01$
        - Client01$
      MemberOf:
        - Service Users

Recommended Lookup Options in Datum.yml (Excerpt)

lookup_options:

  AddsDomainPrincipals:
    merge_hash: deep
  AddsDomainPrincipals\Computers:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - ComputerName
  AddsDomainPrincipals\Users:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - UserName
  AddsDomainPrincipals\ManagedServiceAccounts:
    merge_hash_array: UniqueKeyValTuples
    merge_options:
      tuple_keys:
        - ServiceAccountName