Introduction

The xActiveDirectory module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains the xADDomain, xADDomainController, xADUser, xWaitForDomain, and xADDomainTrust resources. These DSC Resources allow you to configure and manage Active Directory.  Note: these resources do not presently install the RSAT tools.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The "x" in xActiveDirectory stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xActiveDirectory module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point). There are also great community resources, such as PowerShell.org , or PowerShell Magazine . For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xActiveDirectory module

  • Unzip the content under $env:ProgramFiles\WindowsPowerShell\Modules folder

To confirm installation:

  • Run Get-DSCResource to see that xADDomain, xADDomainController, xADUser, xWaitForDomain, and xADDomainTrust are among the DSC Resources listed

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0. Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xActiveDirectory module contains the xADDomain, xADDomainController, xADUser, xWaitForDomain, and ADDomainTrust DSC Resources. These DSC Resources allow you to configure new domain, child domains,high availability domain controllers and establish cross-domain trusts.  The xADDomain resource is responsible to create new Active directory forest configuration or new Active directory domain configuration.  The xADDomainController resource is responsible to install a domain controller in Active directory.  The xADUser resource is responsible to modify or remove Active directory User.  The xWaitForDomain resource is responsible to wait for new domain to setup. It's worth noting that the RSAT tools will not be installed when these resources are used to configure AD. The xADDomainTrust resource is used to establish a cross-domain trust. 

Details

xADDomain resource has following properties:

  • DomainName:                                        Name of the domain.  If no parent name is specified, this is the fully qualified domain name for first domain in the forest.
  • ParentDomainName:                            Name of the parent domain.
  • DomainAdministratorCredential:       Credentials used to query for domain existence. Note: These are not used during domain creation. ( AD sets the localadmin credentials as new domain administrator credentials during setup )
  • SafemodeAdministratorPassword:     Password for the administrator account when the computer is started in Safe Mode.
  • DnsDelegationCredential:                     Credential used for creating DNS delegation
  • DatabasePath:                                         Destination path for the AD database
  • LogPath:                                                    Destination path for the AD log files
  • SysvolPath:                                               Destination path for the sysvol store

xADDomainController resource has following properties:

  • DomainName:                                          The fully qualified domain name for the domain where the domain controller will be present
  • DomainAdministratorCredential:        Specifies the credential for the account used to install the domain controller
  • SafemodeAdministratorPassword:      Password for the administrator account when the computer is started in Safe Mode.
  • DatabasePath:                                         Destination path for the AD database
  • LogPath:                                                    Destination path for the AD log files
  • SysvolPath:                                               Destination path for the sysvol store

xADUser resource has following properties:

  • Ensure:                                                       Specifies whether the given user is present or absent
  • DomainName:                                          Name of the domain to which the user will be added
  • UserName:                                                Name of the user
  • Password:                                                  Password value for the account
  • DomainAdministratorCredential:         User account credentials used to perform the task

xWaitForADDomain resource has following properties:

  • DomainName:                                           Name of the domain to wait for
  • RetryIntervalSec:                                      Interval to check for the domain's existance
  • RetryCount:                                                Maximum number of retries to check for the domain's existance

xADDomainTrust resource has following properties:

  • Ensure:                                                            Specifies whether the domain trust is present or absent
  • TargetDomainAdministratorCredential: Credentials to authenticate to the target domain
  • TargetDomainName:                                   Name of the AD domain that is being trusted
  • TrustType:                                                      Type of trust
  • 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

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the "x" with "c" (short for "Community") or another prefix of your choice:
    • Module name (ex: xADDomain becomes cADDomain)
    • Resource folder (ex: MSFT_xADDomain becomes Contoso_xADDomain)
    • Resource Name (ex: MSFT_xADDomain becomes Contoso_cADDomain)
    • Resource Friendly Name (ex: xADDomain becomes cADDomain)
    • MOF class name (ex: MSFT_xADDomain becomes Contoso_cADDomain)
    • Filename for the <resource>.schema.mof (ex: MSFT_xADDomain.schema.mof becomes Contoso_cADDomain.schema.mof)
  2. Update module and metadata information in the module manifest
  3. Update any configuration that use these resources

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_ADDomain" or "MSFT_ADUser"). If the next version of Windows Server ships with a "ADDomain" resource, we don't want to break any configurations that use any community modifications. Please keep a prefix such as "c" on all community modifications.

Versions

1.0.0.0

  • Initial release with the following resources
    • xADDomain, xADDomainController, xADUser, and xWaitForDomain

2.0.0.0

  • Updated release, which added the resource
    • xADDomainTrust

2.1.0.0

  • Minor update: Get-TargetResource to use domain name instead of name

2.2

  • Modified xAdDomain and xAdDomainController to support Ensure as Present / Absent, rather than True/False. Note: this may cause issues for existing scripts. Also corrected return value to be a hashtable in both resources.

2.3

  • Added properties to xAdDomain and xAdDomainController:
    • DatabasePath
    • LogPath
    • SysvolPath

Example: Create a highly available Domain using multiple domain controllers

In the following example configuration, a highly available domain is created by adding a domain controller to an existing domain.  This example uses the xWaitForDomain resource to ensure that the domain is present before the second domain controller is added.

PowerShell
Edit|Remove
# A configuration to Create High Availability Domain Controller  
 
configuration AssertHADC 
{ 
 
   param 
    ( 
        [Parameter(Mandatory)] 
        [pscredential]$safemodeAdministratorCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$domainCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$DNSDelegationCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$NewADUserCred 
    ) 
 
    Import-DscResource -ModuleName xActiveDirectory 
 
    Node $AllNodes.Where{$_.Role -eq "Primary DC"}.Nodename 
    { 
        WindowsFeature ADDSInstall 
        { 
            Ensure = "Present" 
            Name = "AD-Domain-Services" 
        } 
 
        xADDomain FirstDS 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domainCred 
            SafemodeAdministratorPassword = $safemodeAdministratorCred 
            DnsDelegationCredential = $DNSDelegationCred 
            DependsOn = "[WindowsFeature]ADDSInstall" 
        } 
 
        xWaitForADDomain DscForestWait 
        { 
            DomainName = $Node.DomainName 
            DomainUserCredential = $domainCred 
            RetryCount = $Node.RetryCount 
            RetryIntervalSec = $Node.RetryIntervalSec 
            DependsOn = "[xADDomain]FirstDS" 
        } 
 
        xADUser FirstUser 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domainCred 
            UserName = "dummy" 
            Password = $NewADUserCred 
            Ensure = "Present" 
            DependsOn = "[xWaitForADDomain]DscForestWait" 
        } 
 
    } 
 
    Node $AllNodes.Where{$_.Role -eq "Replica DC"}.Nodename 
    { 
        WindowsFeature ADDSInstall 
        { 
            Ensure = "Present" 
            Name = "AD-Domain-Services" 
        } 
 
        xWaitForADDomain DscForestWait 
        { 
            DomainName = $Node.DomainName 
            DomainUserCredential = $domainCred 
            RetryCount = $Node.RetryCount 
            RetryIntervalSec = $Node.RetryIntervalSec 
            DependsOn = "[WindowsFeature]ADDSInstall" 
        } 
 
        xADDomainController SecondDC 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domainCred 
            SafemodeAdministratorPassword = $safemodeAdministratorCred 
            DnsDelegationCredential = $DNSDelegationCred 
            DependsOn = "[xWaitForADDomain]DscForestWait" 
        } 
    } 
} 
 
# Configuration Data for AD  
 
$ConfigData = @{ 
    AllNodes = @( 
        @{ 
            Nodename = "dsc-testNode1" 
            Role = "Primary DC" 
            DomainName = "dsc-test.contoso.com" 
            CertificateFile = "C:\publicKeys\targetNode.cer"   
            Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"  
            RetryCount = 20  
            RetryIntervalSec = 30  
        }, 
 
        @{ 
            Nodename = "dsc-testNode2" 
            Role = "Replica DC" 
            DomainName = "dsc-test.contoso.com" 
            CertificateFile = "C:\publicKeys\targetNode.cer"   
            Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"  
            RetryCount = 20  
            RetryIntervalSec = 30  
        } 
    ) 
} 
 
AssertHADC -configurationData $ConfigData ` 
-safemodeAdministratorCred (Get-Credential -Message "New Domain Safe Mode Admin Credentials") ` 
-domainCred (Get-Credential -Message "New Domain Admin Credentials") ` 
-DNSDelegationCred (Get-Credential -Message "Credentials to Setup DNS Delegation") ` 
-NewADUserCred (Get-Credential -Message "New AD User Credentials") 
 
Start-DscConfiguration -Wait -Force -Verbose -ComputerName "dsc-testNode1" -Path $PSScriptRoot\AssertHADC ` 
-Credential (Get-Credential -Message "Local Admin Credentials on Remote Machine") 
 
Start-DscConfiguration -Wait -Force -Verbose -ComputerName "dsc-testNode2" -Path $PSScriptRoot\AssertHADC ` 
-Credential (Get-Credential -Message "Local Admin Credentials on Remote Machine") 
 

Example: Create a child domain under a parent domain

In this example, we create a domain, and then create a child domain on another node.

 

PowerShell
Edit|Remove
# Configuration to Setup Parent Child Domains  
 
configuration AssertParentChildDomains 
{ 
    param 
    ( 
        [Parameter(Mandatory)] 
        [pscredential]$safemodeAdministratorCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$domainCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$DNSDelegationCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$NewADUserCred 
    ) 
 
    Import-DscResource -ModuleName xActiveDirectory 
 
    Node $AllNodes.Where{$_.Role -eq "Parent DC"}.Nodename 
    { 
        WindowsFeature ADDSInstall 
        { 
            Ensure = "Present" 
            Name = "AD-Domain-Services" 
        } 
 
        xADDomain FirstDS 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domainCred 
            SafemodeAdministratorPassword = $safemodeAdministratorCred 
            DnsDelegationCredential = $DNSDelegationCred 
            DependsOn = "[WindowsFeature]ADDSInstall" 
        } 
 
        xWaitForADDomain DscForestWait 
        { 
            DomainName = $Node.DomainName 
            DomainUserCredential = $domainCred 
            RetryCount = $Node.RetryCount 
            RetryIntervalSec = $Node.RetryIntervalSec 
            DependsOn = "[xADDomain]FirstDS" 
        } 
 
        xADUser FirstUser 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domaincred 
            UserName = "dummy" 
            Password = $NewADUserCred 
            Ensure = "Present" 
            DependsOn = "[xWaitForADDomain]DscForestWait" 
        } 
 
    } 
 
    Node $AllNodes.Where{$_.Role -eq "Child DC"}.Nodename 
    { 
        WindowsFeature ADDSInstall 
        { 
            Ensure = "Present" 
            Name = "AD-Domain-Services" 
        } 
 
        xWaitForADDomain DscForestWait 
        { 
            DomainName = $Node.ParentDomainName 
            DomainUserCredential = $domainCred 
            RetryCount = $Node.RetryCount 
            RetryIntervalSec = $Node.RetryIntervalSec 
            DependsOn = "[WindowsFeature]ADDSInstall" 
        } 
 
        xADDomain ChildDS 
        { 
            DomainName = $Node.DomainName 
            ParentDomainName = $Node.ParentDomainName 
            DomainAdministratorCredential = $domainCred 
            SafemodeAdministratorPassword = $safemodeAdministratorCred 
            DependsOn = "[xWaitForADDomain]DscForestWait" 
        } 
    } 
} 
 
$ConfigData = @{ 
 
    AllNodes = @( 
        @{ 
            Nodename = "dsc-testNode1" 
            Role = "Parent DC" 
            DomainName = "dsc-test.contoso.com"         
            CertificateFile = "C:\publicKeys\targetNode.cer"   
            Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"  
            RetryCount = 50  
            RetryIntervalSec = 30  
        }, 
 
        @{ 
            Nodename = "dsc-testNode2" 
            Role = "Child DC" 
            DomainName = "dsc-child" 
            ParentDomainName = "dsc-test.contoso.com"              
            CertificateFile = "C:\publicKeys\targetNode.cer"   
            Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"  
            RetryCount = 50  
            RetryIntervalSec = 30         
        } 
    ) 
} 
 
AssertParentChildDomains -configurationData $ConfigData ` 
-safemodeAdministratorCred (Get-Credential -Message "New Domain Safe Mode Admin Credentials") ` 
-domainCred (Get-Credential -Message "New Domain Admin Credentials") ` 
-DNSDelegationCred (Get-Credential -Message "Credentials to Setup DNS Delegation") ` 
-NewADUserCred (Get-Credential -Message "New AD User Credentials") 
 
 
Start-DscConfiguration -Wait -Force -Verbose -ComputerName "dsc-testNode1" -Path $PSScriptRoot\AssertParentChildDomains ` 
-Credential (Get-Credential -Message "Local Admin Credentials on Remote Machine") 
Start-DscConfiguration -Wait -Force -Verbose -ComputerName "dsc-testNode2" -Path $PSScriptRoot\AssertParentChildDomains ` 
-Credential (Get-Credential -Message "Local Admin Credentials on Remote Machine") 
 
 

Example: Create a cross-domain trust

In this example, we setup one-way trust between two domains

 

PowerShell
Edit|Remove
# Configuration to Setup Parent Child Domains  
 
configuration AssertParentChildDomains 
{ 
    param 
    ( 
        [Parameter(Mandatory)] 
        [pscredential]$safemodeAdministratorCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$domainCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$DNSDelegationCred, 
 
        [Parameter(Mandatory)] 
        [pscredential]$NewADUserCred 
    ) 
 
    Import-DscResource -ModuleName xActiveDirectory 
 
    Node $AllNodes.Where{$_.Role -eq "Parent DC"}.Nodename 
    { 
        WindowsFeature ADDSInstall 
        { 
            Ensure = "Present" 
            Name = "AD-Domain-Services" 
        } 
 
        xADDomain FirstDS 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domainCred 
            SafemodeAdministratorPassword = $safemodeAdministratorCred 
            DnsDelegationCredential = $DNSDelegationCred 
            DependsOn = "[WindowsFeature]ADDSInstall" 
        } 
 
        xWaitForADDomain DscForestWait 
        { 
            DomainName = $Node.DomainName 
            DomainUserCredential = $domainCred 
            RetryCount = $Node.RetryCount 
            RetryIntervalSec = $Node.RetryIntervalSec 
            DependsOn = "[xADDomain]FirstDS" 
        } 
 
        xADUser FirstUser 
        { 
            DomainName = $Node.DomainName 
            DomainAdministratorCredential = $domaincred 
            UserName = "dummy" 
            Password = $NewADUserCred 
            Ensure = "Present" 
            DependsOn = "[xWaitForADDomain]DscForestWait" 
        } 
 
    } 
 
    Node $AllNodes.Where{$_.Role -eq "Child DC"}.Nodename 
    { 
        WindowsFeature ADDSInstall 
        { 
            Ensure = "Present" 
            Name = "AD-Domain-Services" 
        } 
 
        xWaitForADDomain DscForestWait 
        { 
            DomainName = $Node.ParentDomainName 
            DomainUserCredential = $domainCred 
            RetryCount = $Node.RetryCount 
            RetryIntervalSec = $Node.RetryIntervalSec 
            DependsOn = "[WindowsFeature]ADDSInstall" 
        } 
 
        xADDomain ChildDS 
        { 
            DomainName = $Node.DomainName 
            ParentDomainName = $Node.ParentDomainName 
            DomainAdministratorCredential = $domainCred 
            SafemodeAdministratorPassword = $safemodeAdministratorCred 
            DependsOn = "[xWaitForADDomain]DscForestWait" 
        } 
    } 
} 
 
$ConfigData = @{ 
 
    AllNodes = @( 
        @{ 
            Nodename = "dsc-testNode1" 
            Role = "Parent DC" 
            DomainName = "dsc-test.contoso.com"         
            CertificateFile = "C:\publicKeys\targetNode.cer"   
            Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"  
            RetryCount = 50  
            RetryIntervalSec = 30  
        }, 
 
        @{ 
            Nodename = "dsc-testNode2" 
            Role = "Child DC" 
            DomainName = "dsc-child" 
            ParentDomainName = "dsc-test.contoso.com"              
            CertificateFile = "C:\publicKeys\targetNode.cer"   
            Thumbprint = "AC23EA3A9E291A75757A556D0B71CBBF8C4F6FD8"  
            RetryCount = 50  
            RetryIntervalSec = 30         
        } 
    ) 
} 
 
AssertParentChildDomains -configurationData $ConfigData ` 
-safemodeAdministratorCred (Get-Credential -Message "New Domain Safe Mode Admin Credentials") ` 
-domainCred (Get-Credential -Message "New Domain Admin Credentials") ` 
-DNSDelegationCred (Get-Credential -Message "Credentials to Setup DNS Delegation") ` 
-NewADUserCred (Get-Credential -Message "New AD User Credentials") 
 
 
Start-DscConfiguration -Wait -Force -Verbose -ComputerName "dsc-testNode1" -Path $PSScriptRoot\AssertParentChildDomains ` 
-Credential (Get-Credential -Message "Local Admin Credentials on Remote Machine") 
Start-DscConfiguration -Wait -Force -Verbose -ComputerName "dsc-testNode2" -Path $PSScriptRoot\AssertParentChildDomains ` 
-Credential (Get-Credential -Message "Local Admin Credentials on Remote Machine")