Creating an Active Directory domain with PowerShell DSC

With the help of PowerShell DSC, you can automate the creation of an Active Directory domain. This includes promoting a member server to a domain controller and creating users, groups, and containers. This can be particularly helpful when you want to set up a test domain quickly.

One of the most common components of any test environment is Active Directory (AD). AD is a critical part of most environments and is one we need to replicate as closely as possible to production in a test environment. Before technologies like PowerShell Desired State Configuration (DSC) came along, we had to copy the AD database over manually, bring up entirely new domain controllers from scratch, and a lot of other hacks. Nowadays, we can invoke a DSC configuration script that can bring up an entirely new AD domain in no time!

Prerequisites ^

To automate creating a test domain with DSC, we'll need to ensure we've got a few prerequisites in place. First, we'll need an existing server (physical or virtual) in a workgroup. Next, we'll need to make sure this server has at least PowerShell v4 installed and preferably v5.

In the demonstration, we'll be creating the DSC configuration on another machine and sending it to the server that will be our domain controller. Although it's not necessary if performing the work locally, this computer will need to be able to communicate with the soon-to-be domain controller via Server Message Block (SMB).

Finally, you'll need to have the xActiveDirectory DSC module installed on the server. You can download this by running the following:

Project scope ^

Creating an AD domain can mean a lot to many different people since it's such a large topic. So let's scope our DSC configuration script down a bit. For this article, we'll be:

  • Promoting a member server to a domain controller
  • Creating multiple groups
  • Creating multiple users
  • Creating multiple organizational units

This isn't, by far, everything that's possible. But with the framework down, you can add additional objects to your DSC configuration script more easily later.

Defining Configuration Data ^

A best practice to use when creating any DSC configuration script is to separate the actual configuration itself from the configuration data. Configuration data can consist of any "static" values the code needs to reference when running. In our case, it includes the domain name, group names, organizational unit paths, and so on. The first task to tackle is defining all of these values in a PSD1 file that contains a hash table with all the data we need.

To expedite the process of creating this file, I've created an example you can download from the TestDomainCreator GitHub repository.

This file holds all the configuration item values we need to create a fully functional AD domain.

Creating the DSC configuration script ^

Next, we need to create the DSC configuration. We can break down this configuration into the four topics I described above. Since we've already created a separate configuration data file, we'll need to reference this inside the DSC configuration script. We'll use the $ConfigurationData variable automatically available in all DSC configuration scripts (if using the ConfigurationData parameter when invoking Start-DscConfiguration).

You can download an example script from GitHub. You'll see from the example that the DSC configuration script is calling each of the AD objects we're creating (groups, organizational units, and users). It then references the appropriate DSC resource within the xActiveDirectory DSC module we downloaded earlier.

The only section of the DSC configuration script that does not fit this mold is when we're installing the appropriate Windows features and promoting the server to a domain controller.

Once you've downloaded the DSC configuration script and the configuration data, and you've tweaked them to your liking, you can then create the MOF file. After this, we can then invoke the file on the server.

WARNING: The configuration 'NewTestEnvironment' is loading one or more built-in resources without explicitly importing associated modules. Add Import-DscResource –ModuleName 'PSDesiredStateConfiguration' to your configuration to avoid this message.

Above I'm creating the MOF file for the server I have called LABDC.

Once I've created the MOF file, I can then invoke the DSC configuration on my remote server by running Start-DscConfiguration.

Start DscConfiguration

Start DscConfiguration

Notice that I'm using a credential. This is necessary because the server you'll be running the DSC configuration script on will be in a workgroup. Thus, you must provide an administrative username and password to make that initial connection.

After finishing this process, you will then have a brand new AD domain running on your server!

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

  1. Jimmy 2 years ago


    thanks for your post

    is it possible to customise this configuration in order to create :

    - a real OU structure ( OU / sub OU / sub Ou ...)

    - define in wich OU  groups and users should be created?



  2. Jimmy 2 years ago

    Sorry, just saw the « path » function, could you just please explain how the path function works in order to define the path?

    (-f ?)



  3. mike 1 year ago

    Didn't find your test users amusing.


  4. tank 4 months ago

    I did find your test users amusing


  5. This is definitely not the place to be advertising your politics. 

    David F. 


Leave a reply

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2020


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account