Configuring Active Directory with PowerShell DSC and the New xADRecycleBin Resource

Artikel
07/15/2015

Active Directory and PowerShell DSC

Today’s post is the second in a series on using PowerShell DSC with Active Directory. We will demonstrate configuring the AD Recycle Bin and domain trusts with PowerShell Desired State Configuration. As a bonus we will throw in a registry key for some special logging on the domain controller.

Continuing where we left off…

In a previous post we looked at how to build a domain controller with DSC. Recently Don Jones and Hemant Mahawar recorded a Microsoft Virtual Academy video demonstrating this as well. I encourage you to check it out for more background on building domains with PowerShell DSC.

Once we have a domain built there are some additional steps we may want to implement like creating trusts and enabling the recycle bin. Below I have provided sample DSC configuration code to do just that. You can run it as-is, or manually merge it into the code from the previous article for one massive build script.

Prerequisites

You will need to download and install the latest version of the xActiveDirectory resource module. Follow the instructions at powershellgallery.com. Also, I used the latest release of WMF 5.0 to apply this configuration in my lab.

A new DSC resource: xADRecycleBin

Months ago when the PowerShell team started tinkering with hosting the DSC Resource Kit on GitHub I was one of the first to contribute a new resource. You can read about the new open source DSC resource kit at this blog post from the PowerShell team.

After you build a new forest, enabling the AD Recycle Bin is a manual step. This sounded like the next logical resource to me, so I wrote it, tested it, and submitted a pull request on GitHub for the team to include it in the resource kit. I am a GitHub newb, so I am grateful for their assistance publishing this. Note that you should download resources from PowerShellGallery.com (not GitHub) for the latest production builds. Today’s post includes a demo of the new resource.

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.) It has the following parameters:

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.
DependsOn: Automatic parameter used to validate that the forest is available using a previous xWaitForADDomain resource.

See the sample code below for usage. Here is the output from Get-DscConfiguration showing the results after the configuration is applied:

 PS C:\> Get-DscConfiguration

ConfigurationName                 : ConfigDomain
DependsOn                         : {[xWaitForADDomain]DscForestWait}
ModuleName                        : xActiveDirectory
ModuleVersion                     : 2.4.0.0
PsDscRunAsCredential              : 
ResourceId                        : [xADRecycleBin]RecycleBin
SourceInfo                        : 
EnterpriseAdministratorCredential : 
ForestFQDN                        : alpineskihouse.com
ForestMode                        : Windows2012R2Forest
RecycleBinEnabled                 : true
PSComputerName                    : 
CimClassName                      : MSFT_xADRecycleBin

Note that the AD Recycle Bin is a feature of the FOREST, not every domain controller that you build with DSC. This should only ever be done once per forest. I wrote the resource especially for those who want to rebuild lab environments over and over. This will save you a step each time.

xADDomainTrust

This resource has been around for a while. See the sample code below, creating a bidirectional external trust between Contoso.com and AlpineSkiHouse.com. Notice that you need an additional credential for the remote domain to build the trust. You can pass this in as a parameter for ease of use.

Registry

There are tons of registry keys available to tweak the performance and configuration of a domain controller. The one in my example is a low-impact logging adjustment so that the garbage collection event will also include a statistic for the white space percentage in the AD database on the local server. We use this frequently with Premier customers when we assess the health and risk of their Active Directory environment.

Following this example below, take a look at your current domain controller build script and migrate any custom registry values into your DSC configuration.

Show me some DSC!

Here is the DSC script I used to apply these settings to my new domain (forest) from the last post. Notice the strategic use of DependsOn to chain the resources together in a specific order. If you copy this code into the previous domain build sample, you will want to add a DependsOn to the first xWaitForADDomain resource below.

 Configuration ConfigDomain             
{            
   Param            
    (             
        [Parameter(Mandatory)]            
        [pscredential]$DomainCred,            
        [Parameter(Mandatory)]             
        [pscredential]$ContosoCred            
    )            
    Import-DscResource -ModuleName PSDesiredStateConfiguration            
    Import-DscResource -ModuleName xActiveDirectory            
            
    Node $AllNodes.Where{$_.Role -eq "Primary DC"}.Nodename            
    {            
            
        xWaitForADDomain DscForestWait            
        {            
            DomainName = $Node.DomainName            
            DomainUserCredential = $DomainCred            
            RetryCount = $Node.RetryCount            
            RetryIntervalSec = $Node.RetryIntervalSec            
        }            
            
        xADRecycleBin RecycleBin            
        {            
           EnterpriseAdministratorCredential = $DomainCred            
           ForestFQDN = $Node.DomainName            
           DependsOn = '[xWaitForADDomain]DscForestWait'            
        }            
            
        # Verify connectivity to contoso.com and build a trust            
        xWaitForADDomain AnybodyHomeContoso            
        {            
            DomainName = 'contoso.com'            
            DomainUserCredential = $ContosoCred            
            RetryCount = $Node.RetryCount            
            RetryIntervalSec = $Node.RetryIntervalSec            
            DependsOn = '[xWaitForADDomain]DscForestWait'            
        }            
            
        xADDomainTrust MyBuddyContoso            
        {            
            SourceDomainName = 'alpineskihouse.com'            
            TargetDomainAdministratorCredential = $ContosoCred            
            TargetDomainName = 'contoso.com'            
            TrustDirection = 'Bidirectional' # Bidirectional,Inbound,Outbound            
            TrustType = 'External'            
            DependsOn = '[xWaitForADDomain]AnybodyHomeContoso'            
            Ensure = 'Present'            
        }            
            
        # DB white space logging, low logging volume            
        # Used in Microsoft Premier ADRAP and ADRaaS assessments            
        # https://support.microsoft.com/en-us/kb/314980            
        Registry DBWhiteSpace            
        {            
            Key = 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\NTDS\Diagnostics'            
            ValueName = '6 Garbage Collection'            
            ValueData = '1'            
            ValueType = 'DWORD'            
            Ensure = 'Present'            
            DependsOn = '[xWaitForADDomain]DscForestWait'            
        }            
            
    }            
}            
            
# Configuration Data for AD              
$ConfigData = @{            
    AllNodes = @(            
        @{            
            Nodename = "localhost"            
            Role = "Primary DC"            
            DomainName = "alpineskihouse.com"            
            RetryCount = 20            
            RetryIntervalSec = 30            
            PsDscAllowPlainTextPassword = $true  # LAB ONLY!            
        }            
    )            
}            
            
ConfigDomain -ConfigurationData $ConfigData `
    -DomainCred (Get-Credential -UserName alpineskihouse\psv5administrator `
        -Message "Domain Admin Credential") `
    -ContosoCred (Get-Credential -UserName contoso\psv5administrator `
        -Message "Contoso Trust Domain Admin Credential")            
            
# Configure the domain            
Start-DscConfiguration -Wait -Force -Path .\ConfigDomain -Verbose

Your Turn

So far we have built a new domain, enabled the recycle bin, added a trust, and configured a DC registry key. Now take this sample code and use it in your own Active Directory lab. Feel free to modify it for your own needs. Later in the series we will look at creating organizational units and users.

Freigeben über