diff --git a/README.md b/README.md index 1829a4a4e..8322dcdad 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,11 @@ Please check out common DSC Resource [contributing guidelines](https://github.co ## Description -The **xActiveDirectory** module contains the **xADComputer, xADDomain, xADDomainController, xADUser, xWaitForDomain, xADDomainTrust, xADRecycleBin, xADGroup, xADOrganizationalUnit, xADReplicationSubnet, xADReplicationSite and xADDomainDefaultPasswordPolicy** DSC Resources. -These DSC Resources allow you to configure new domains, child domains, and high availability domain controllers, establish cross-domain trusts and manage users, groups and OUs. +The **xActiveDirectory** module contains DSC resources for deployment and +configuration of Active Directory. +These DSC resources allow you to configure new domains, child domains, and high +availability domain controllers, establish cross-domain trusts and manage users, +groups and OUs. ## Resources @@ -27,13 +30,42 @@ These DSC Resources allow you to configure new domains, child domains, and high * **xADDomainTrust** establishes cross-domain trusts. * **xADGroup** modifies and removes Active Directory groups. * **xADOrganizationalUnit** creates and deletes Active Directory OUs. +* **xADRecycleBin** enables or disabled Active Directory Recycle Bin. * **xADReplicationSite** creates and deletes Active Directory replication sites. -* **xADUser** modifies and removes Active Directory Users. +* **xADReplicationSubnet** add or removes Active Directory replication subnet. * **xADServicePrincipalName** adds or removes the SPN to a user or computer account. +* **xADUser** modifies and removes Active Directory Users. * **xWaitForDomain** waits for new, remote domain to setup. (Note: the RSAT tools will not be installed when these resources are used to configure AD.) +### **xADComputer** + +The xADComputer DSC resource will manage computer accounts within Active Directory. + +* **ComputerName**: Specifies the name of the computer to manage. +* **Location**: Specifies the location of the computer, such as an office number (optional). +* **DnsHostName**: Specifies the fully qualified domain name (FQDN) of the computer (optional). +* **ServicePrincipalNames**: Specifies the service principal names for the computer account (optional). +* **UserPrincipalName** :Specifies the UPN assigned to the computer account (optional). +* **DisplayName**: "Specifies the display name of the computer (optional). +* **Path**: Specifies the X.500 path of the container where the computer is located (optional). +* **Description**: Specifies a description of the computer object (optional). +* **Enabled**: Specifies if the computer account is enabled (optional). +* **Manager**: Specifies the user or group Distinguished Name that manages the computer object (optional). + * Valid values are the user's or group's DistinguishedName, ObjectGUID, SID or SamAccountName. +* **DomainController**: Specifies the Active Directory Domain Services instance to connect to perform the task (optional). +* **DomainAdministratorCredential**: Specifies the user account credentials to use to perform the task (optional). +* **RequestFile**: Specifies the full path to the Offline Domain Join Request file to create (optional). +* **Ensure**: Specifies whether the computer account is present or absent. + * Valid values are 'Present' and 'Absent'. + * It not specified, it defaults to 'Present'. +* **DistinguishedName**: Returns the X.500 path of the computer object (read-only). +* **SID**: Returns the security identifier of the computer object (read-only). + +Note: An ODJ Request file will only be created when a computer account is first created in the domain. +Setting an ODJ Request file path for a configuration that creates a computer account that already exists will not cause the file to be created. + ### **xADDomain** * **DomainName**: Name of the domain. @@ -63,85 +95,22 @@ These DSC Resources allow you to configure new domains, child domains, and high * **SiteName**: Specify the name of an existing site where new domain controller will be placed. (optional) * **IsGlobalCatalog**: Specify if the new Domain Controller will be a Global Catalog Server (Default = $True, Optional) -### **xADReplicationSite** - -* **Ensure**: Specifies if the AD replication site should be added or remove. Default value is 'Present'. { *Present* | Absent }. -* **Name**: Specifies the name of the AD replication site. -* **RenameDefaultFirstSiteName**: Specify if the Default-First-Site-Name should be renamed, if it exists. Dafult value is 'false'. - -### **xADUser** - -* **DomainName**: Name of the domain to which the user will be added. - * The Active Directory domain's fully-qualified domain name must be specified, i.e. contoso.com. - * This parameter is used to query and set the user's account password. -* **UserName**: Specifies the Security Account Manager (SAM) account name of the user. - * 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. -* **Password**: Password value for the user account. - * _If the account is enabled (default behaviour) you must specify a password._ - * _You must ensure that the password meets the domain's complexity requirements._ -* **Ensure**: Specifies whether the given user is present or absent (optional). - * If not specified, this value defaults to Present. -* **DomainController**: Specifies the Active Directory Domain Services instance to connect to (optional). - * This is only required if not executing the task on a domain controller. -* **DomainAdministratorCredential**: User account credentials used to perform the task (optional). - * This is only required if not executing the task on a domain controller or using the -DomainController parameter. -* **CommonName**: Specifies the user's CN of the user account (optional). - * If not specified, this defaults to the ___UserName___ value. -* **UserPrincipalName**: Each user account has a user principal name (UPN) in the format [user]@[DNS-domain-name] (optional). -* **DisplayName**: Specifies the display name of the user object (optional). -* **Path**: (optional). -* **GivenName**: Specifies the user's first or given name (optional). -* **Initials**: Specifies the initials that represent part of a user's name (optional). -* **Surname**: Specifies the user's last name or surname (optional). -* **Description**: Specifies a description of the user object (optional). -* **StreetAddress**: Specifies the user's street address (optional). -* **POBox**: Specifies the user's post office box number (optional). -* **City**: Specifies the user's town or city (optional). -* **State**: Specifies the user's state or province (optional). -* **PostalCode**: Specifies the user's postal code or zip code (optional). -* **Country**: Specifies the country or region code for the user's language of choice (optional). - * This should be specified as the country's two character ISO-3166 code. -* **Department**: Specifies the user's department (optional). -* **Division**: Specifies the user's division (optional). -* **Company**: Specifies the user's company (optional). -* **Office**: Specifies the location of the user's office or place of business (optional). -* **JobTitle**: Specifies the user's job title (optional). -* **EmailAddress**: Specifies the user's e-mail address (optional). -* **EmployeeID**: Specifies the user's employee ID (optional). -* **EmployeeNumber**: Specifies the user's employee number (optional). -* **HomeDirectory**: Specifies a user's home directory path (optional). -* **HomeDrive**: Specifies a drive that is associated with the UNC path defined by the HomeDirectory property (optional). - * The drive letter is specified as "[DriveLetter]:" where [DriveLetter] indicates the letter of the drive to associate. - * The [DriveLetter] must be a single, uppercase letter and the colon is required. -* **HomePage**: Specifies the URL of the home page of the user object (optional). -* **ProfilePath**: Specifies a path to the user's profile (optional). - * This value can be a local absolute path or a Universal Naming Convention (UNC) path. -* **LogonScript**: Specifies a path to the user's log on script (optional). - * This value can be a local absolute path or a Universal Naming Convention (UNC) path. -* **Notes**: (optional). -* **OfficePhone**: Specifies the user's office telephone number (optional). -* **MobilePhone**: Specifies the user's mobile phone number (optional). -* **Fax**: Specifies the user's fax phone number (optional). -* **Pager**: Specifies the user's pager number (optional). -* **IPPhone**: Specifies the user's IP telephony number (optional). -* **HomePhone**: Specifies the user's home telephone number (optional). -* **Enabled**: Specifies if an account is enabled (optional). - * An enabled account requires a password. -* **Manager**: Specifies the user's manager (optional). - * This value can be specified as a DN, ObjectGUID, SID or SamAccountName. -* **PasswordNeverExpires**: Specifies whether the password of an account can expire (optional). - * If not specified, this value defaults to False. -* **CannotChangePassword**: Specifies whether the account password can be changed (optional). - * If not specified, this value defaults to False. -* **PasswordAuthentication**: Specifies the authentication context used when testing users' passwords (optional). - * The 'Negotiate' option supports NTLM authentication - which may be required when testing users' passwords when Active Directory Certificate Services (ADCS) is deployed. +### **xADDomainDefaultPasswordPolicy** -### **xWaitForADDomain** +The xADDomainDefaultPasswordPolicy DSC resource will manage an Active Directory domain's default password policy. -* **DomainName**: Name of the remote domain. -* **RetryIntervalSec**: Interval to check for the domain's existence. -* **RetryCount**: Maximum number of retries to check for the domain's existence. +* **DomainName**: Name of the domain to which the password policy will be applied. +* **ComplexityEnabled**: Whether password complexity is enabled for the default password policy. +* **LockoutDuration**: Length of time that an account is locked after the number of failed login attempts (minutes). +* **LockoutObservationWindow**: Maximum time between two unsuccessful login attempts before the counter is reset to 0 (minutes). +* **LockoutThreshold**: Number of unsuccessful login attempts that are permitted before an account is locked out. +* **MinPasswordAge**: Minimum length of time that you can have the same password (minutes). +* **MaxPasswordAge**: Maximum length of time that you can have the same password (minutes). +* **MinPasswordLength**: Minimum number of characters that a password must contain. +* **PasswordHistoryCount**: Number of previous passwords to remember. +* **ReversibleEncryptionEnabled**: Whether the directory must store passwords using reversible encryption. +* **DomainController**: An existing Active Directory domain controller used to perform the operation (optional). +* **Credential**: User account credentials used to perform the operation (optional). ### **xADDomainTrust** @@ -152,19 +121,6 @@ These DSC Resources allow you to configure new domains, child domains, and high * **TrustDirection**: Direction of trust, the values for which may be Bidirectional,Inbound, or Outbound * **SourceDomainName**: Name of the AD domain that is requesting the trust -### **xADRecycleBin** - -The xADRecycleBin DSC resource will enable the Active Directory Recycle Bin feature for the target forest. -This resource first verifies that the forest mode is Windows Server 2008 R2 or greater. If the forest mode -is insufficient, then the resource will exit with an error message. The change is executed against the -Domain Naming Master FSMO of the forest. -(Note: This resource is compatible with a Windows 2008 R2 or above target node.) - -* **ForestFQDN**: Fully qualified domain name of forest to enable Active Directory Recycle Bin. -* **EnterpriseAdministratorCredential**: Credential with Enterprise Administrator rights to the forest. -* **RecycleBinEnabled**: Read-only. Returned by Get. -* **ForestMode**: Read-only. Returned by Get. - ### **xADGroup** The xADGroup DSC resource will manage groups within Active Directory. @@ -219,22 +175,24 @@ The xADOrganizational Unit DSC resource will manage OUs within Active Directory. * **Ensure**: Specifies whether the OU is present or absent. Valid values are 'Present' and 'Absent'. It not specified, it defaults to 'Present'. * **Credential**: User account credentials used to perform the operation (optional). Note: _if not running on a domain controller, this is required_. -### **xADDomainDefaultPasswordPolicy** +### **xADRecycleBin** -The xADDomainDefaultPasswordPolicy DSC resource will manage an Active Directory domain's default password policy. +The xADRecycleBin DSC resource will enable the Active Directory Recycle Bin feature for the target forest. +This resource first verifies that the forest mode is Windows Server 2008 R2 or greater. If the forest mode +is insufficient, then the resource will exit with an error message. The change is executed against the +Domain Naming Master FSMO of the forest. +(Note: This resource is compatible with a Windows 2008 R2 or above target node.) -* **DomainName**: Name of the domain to which the password policy will be applied. -* **ComplexityEnabled**: Whether password complexity is enabled for the default password policy. -* **LockoutDuration**: Length of time that an account is locked after the number of failed login attempts (minutes). -* **LockoutObservationWindow**: Maximum time between two unsuccessful login attempts before the counter is reset to 0 (minutes). -* **LockoutThreshold**: Number of unsuccessful login attempts that are permitted before an account is locked out. -* **MinPasswordAge**: Minimum length of time that you can have the same password (minutes). -* **MaxPasswordAge**: Maximum length of time that you can have the same password (minutes). -* **MinPasswordLength**: Minimum number of characters that a password must contain. -* **PasswordHistoryCount**: Number of previous passwords to remember. -* **ReversibleEncryptionEnabled**: Whether the directory must store passwords using reversible encryption. -* **DomainController**: An existing Active Directory domain controller used to perform the operation (optional). -* **Credential**: User account credentials used to perform the operation (optional). +* **ForestFQDN**: Fully qualified domain name of forest to enable Active Directory Recycle Bin. +* **EnterpriseAdministratorCredential**: Credential with Enterprise Administrator rights to the forest. +* **RecycleBinEnabled**: Read-only. Returned by Get. +* **ForestMode**: Read-only. Returned by Get. + +### **xADReplicationSite** + +* **Ensure**: Specifies if the AD replication site should be added or remove. Default value is 'Present'. { *Present* | Absent }. +* **Name**: Specifies the name of the AD replication site. +* **RenameDefaultFirstSiteName**: Specify if the Default-First-Site-Name should be renamed, if it exists. Dafult value is 'false'. ### **xADReplicationSubnet** @@ -253,32 +211,79 @@ The xADServicePrincipalName DSC resource will manage service principal names. * **ServicePrincipalName**: The full SPN to add or remove, e.g. HOST/LON-DC1. * **Account**: The user or computer account to add or remove the SPN, e.b. User1 or LON-DC1$. Default value is ''. If Ensure is set to Present, a value must be specified. -### **xADComputer** +### **xADUser** -The xADComputer DSC resource will manage computer accounts within Active Directory. +* **DomainName**: Name of the domain to which the user will be added. + * The Active Directory domain's fully-qualified domain name must be specified, i.e. contoso.com. + * This parameter is used to query and set the user's account password. +* **UserName**: Specifies the Security Account Manager (SAM) account name of the user. + * 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. +* **Password**: Password value for the user account. + * _If the account is enabled (default behaviour) you must specify a password._ + * _You must ensure that the password meets the domain's complexity requirements._ +* **Ensure**: Specifies whether the given user is present or absent (optional). + * If not specified, this value defaults to Present. +* **DomainController**: Specifies the Active Directory Domain Services instance to connect to (optional). + * This is only required if not executing the task on a domain controller. +* **DomainAdministratorCredential**: User account credentials used to perform the task (optional). + * This is only required if not executing the task on a domain controller or using the -DomainController parameter. +* **CommonName**: Specifies the user's CN of the user account (optional). + * If not specified, this defaults to the ___UserName___ value. +* **UserPrincipalName**: Each user account has a user principal name (UPN) in the format [user]@[DNS-domain-name] (optional). +* **DisplayName**: Specifies the display name of the user object (optional). +* **Path**: (optional). +* **GivenName**: Specifies the user's first or given name (optional). +* **Initials**: Specifies the initials that represent part of a user's name (optional). +* **Surname**: Specifies the user's last name or surname (optional). +* **Description**: Specifies a description of the user object (optional). +* **StreetAddress**: Specifies the user's street address (optional). +* **POBox**: Specifies the user's post office box number (optional). +* **City**: Specifies the user's town or city (optional). +* **State**: Specifies the user's state or province (optional). +* **PostalCode**: Specifies the user's postal code or zip code (optional). +* **Country**: Specifies the country or region code for the user's language of choice (optional). + * This should be specified as the country's two character ISO-3166 code. +* **Department**: Specifies the user's department (optional). +* **Division**: Specifies the user's division (optional). +* **Company**: Specifies the user's company (optional). +* **Office**: Specifies the location of the user's office or place of business (optional). +* **JobTitle**: Specifies the user's job title (optional). +* **EmailAddress**: Specifies the user's e-mail address (optional). +* **EmployeeID**: Specifies the user's employee ID (optional). +* **EmployeeNumber**: Specifies the user's employee number (optional). +* **HomeDirectory**: Specifies a user's home directory path (optional). +* **HomeDrive**: Specifies a drive that is associated with the UNC path defined by the HomeDirectory property (optional). + * The drive letter is specified as "[DriveLetter]:" where [DriveLetter] indicates the letter of the drive to associate. + * The [DriveLetter] must be a single, uppercase letter and the colon is required. +* **HomePage**: Specifies the URL of the home page of the user object (optional). +* **ProfilePath**: Specifies a path to the user's profile (optional). + * This value can be a local absolute path or a Universal Naming Convention (UNC) path. +* **LogonScript**: Specifies a path to the user's log on script (optional). + * This value can be a local absolute path or a Universal Naming Convention (UNC) path. +* **Notes**: (optional). +* **OfficePhone**: Specifies the user's office telephone number (optional). +* **MobilePhone**: Specifies the user's mobile phone number (optional). +* **Fax**: Specifies the user's fax phone number (optional). +* **Pager**: Specifies the user's pager number (optional). +* **IPPhone**: Specifies the user's IP telephony number (optional). +* **HomePhone**: Specifies the user's home telephone number (optional). +* **Enabled**: Specifies if an account is enabled (optional). + * An enabled account requires a password. +* **Manager**: Specifies the user's manager (optional). + * This value can be specified as a DN, ObjectGUID, SID or SamAccountName. +* **PasswordNeverExpires**: Specifies whether the password of an account can expire (optional). + * If not specified, this value defaults to False. +* **CannotChangePassword**: Specifies whether the account password can be changed (optional). + * If not specified, this value defaults to False. +* **PasswordAuthentication**: Specifies the authentication context used when testing users' passwords (optional). + * The 'Negotiate' option supports NTLM authentication - which may be required when testing users' passwords when Active Directory Certificate Services (ADCS) is deployed. -* **ComputerName**: Specifies the name of the computer to manage. -* **Location**: Specifies the location of the computer, such as an office number (optional). -* **DnsHostName**: Specifies the fully qualified domain name (FQDN) of the computer (optional). -* **ServicePrincipalNames**: Specifies the service principal names for the computer account (optional). -* **UserPrincipalName** :Specifies the UPN assigned to the computer account (optional). -* **DisplayName**: "Specifies the display name of the computer (optional). -* **Path**: Specifies the X.500 path of the container where the computer is located (optional). -* **Description**: Specifies a description of the computer object (optional). -* **Enabled**: Specifies if the computer account is enabled (optional). -* **Manager**: Specifies the user or group Distinguished Name that manages the computer object (optional). - * Valid values are the user's or group's DistinguishedName, ObjectGUID, SID or SamAccountName. -* **DomainController**: Specifies the Active Directory Domain Services instance to connect to perform the task (optional). -* **DomainAdministratorCredential**: Specifies the user account credentials to use to perform the task (optional). -* **RequestFile**: Specifies the full path to the Offline Domain Join Request file to create (optional). -* **Ensure**: Specifies whether the computer account is present or absent. - * Valid values are 'Present' and 'Absent'. - * It not specified, it defaults to 'Present'. -* **DistinguishedName**: Returns the X.500 path of the computer object (read-only). -* **SID**: Returns the security identifier of the computer object (read-only). +### **xWaitForADDomain** -Note: An ODJ Request file will only be created when a computer account is first created in the domain. -Setting an ODJ Request file path for a configuration that creates a computer account that already exists will not cause the file to be created. +* **DomainName**: Name of the remote domain. +* **RetryIntervalSec**: Interval to check for the domain's existence. +* **RetryCount**: Maximum number of retries to check for the domain's existence. ## Versions @@ -286,6 +291,10 @@ Setting an ODJ Request file path for a configuration that creates a computer acc * xAdDomainController: Add Option to disable or enable the global catalog per issue #75 * xAdDomainController: Fix to get-dscconfiguration issue with Ensure (Reference to Pull Request #111) +* Changes to xActiveDirectory + * The resources are now in alphabetical order in the README.md + ([issue #194](https://github.com/PowerShell/xActiveDirectory/issues/194)). + ### 2.18.0.0 * xADReplicationSite: Resource added.