Introduction

Sometimes you can’t find the DSC resource you need built into Windows. For example, let’s say you want to deploy a certificate from your CA – the DSC resource just doesn’t exist but then there’s GitHub. I’ll demo how you can search for and install the xCertificate DSC resource then how to use it in your configuration.

Other parts in this series:

• Learn PowerShell DSC Part 1
• Learn PowerShell DSC Part 2
• Learn PowerShell DSC Part 3
• Learn PowerShell DSC Part 5
• Learn
  PowerShell DSC Part 6
• Learn
  PowerShell DSC Part 7

Find DSC Resources

GitHub is a great repository for DSC resources which are not yet included in Windows. You can go to GitHub and download the additional DSC resources you need or you can just search for them using PowerShell:

Find-Module -Tag dsc

You can also filter by name e.g.

Find-Module -Tag dsc -Name *cert*

Our module is called xCertificate. Now, that was quite easy. Let’s move on.

Install DSC Resource

The DSC resource is actually part of a module which we need to install. To do this, we simply run the command below. It will prompt you to install a NuGet module if you don’t already have it – this is used to get modules from GitHub:

Install-Module xCertificate -Force

We can check our module is installed too:

Get-Module xCertificate -ListAvailable

You need to install the module on the server you’re writing your configuration on and also on the target server (the one that will receive the configuration). In upcoming articles, I’ll explain how to pull configurations using SMB or HTTPS. Using a pull server, you not only have a central repository for configurations but also have a central repository for the modules which are pulled as well. How good is that!?

To save time and install the module on a remote computer (contchidsc01), we can use remote PowerShell to install the NuGet Package Provider and xCertificate module:

icm contchidsc01 {Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
     Install-Module xCertificate -Force
     }

Deploy a certificate with DSC

Okay, so we now have all the pre-requisites we need. We have the DSC resource on our development machine and our target server. Let’s go ahead and write a DSC configuration. If you’re not familiar with this then go back and review part 1. You’ll see I’m using parameters in my configuration – if you’re not familiar with this, go and review part 3.

The plan is to deploy a new certificate to our target server, contchidsc01. The details are below:

• Subject: contchidsc01.contoso.com
• Subject alternative names: contchidsc01.contoso.com, contshidsc01
• Exportable: true
• Certificate Template: Server

configuration HTTPSPullServerCertificate
     {
         Param (
             [Parameter(Mandatory = $true)]
             [string] $ComputerName
         )

        # Modules must exist on target pull server
         Import-DSCResource -ModuleName PSDesiredStateConfiguration
         Import-DscResource -ModuleName xCertificate

        Node $ComputerName
             {
                 $ComputerFqdn = $ComputerName + “.contoso.com”

                xCertReq Certificate
                     {
                         Subject = $ComputerFqdn
                         SubjectAltName = “dns=$ComputerFqdn&dns=$ComputerName”
                         Exportable = $true
                         CertificateTemplate = “Server”
                     }
             }
     }

You’ll see we’re using our new xCertificate module and calling a new resource called xCertReq. The xCertReq DSC resource is what we need to request a certificate from the CA. There are other DSC resources available in the module and you can find all the documentation on GitHub here.

This line below simply gets the FQDN of the computer and saves it as $ComputerFqdn. We use it to add it to the certificate names:

$ComputerFqdn = $ComputerName + “.contoso.com”

Now, let’s create our MOF files:

HTTPSPullServerCertificate -ComputerName contchidsc01 -OutputPath C:DSCCertificate

…..and push our configuration:

Start-DscConfiguration -Path C:DSCCertificate -Verbose -Wait -Force

then test our configuration was deployed successfully:

Test-DscConfiguration -ComputerName contchidsc01 -Path C:DSCCertificate

The entire script is below:

configuration HTTPSPullServerCertificate
     {
         Param (
             [Parameter(Mandatory = $true)]
             [string] $ComputerName
         )

        # Modules must exist on target pull server
         Import-DSCResource -ModuleName PSDesiredStateConfiguration
         Import-DscResource -ModuleName xCertificate

        Node $ComputerName
             {
                 $ComputerFqdn = $ComputerName + “.contoso.com”

                xCertReq Certificate
                     {
                         Subject = $ComputerFqdn
                         SubjectAltName = “dns=$ComputerFqdn&dns=$ComputerName”
                         Exportable = $true
                         CertificateTemplate = “Server”
                     }
             }
     }

#Create MOF file
HTTPSPullServerCertificate -ComputerName contchidsc01 -OutputPath C:DSCCertificate
#Push the configuration
Start-DscConfiguration -Path C:DSCCertificate -Verbose -Wait -Force
#Test the configuration
Test-DscConfiguration -ComputerName contchidsc01 -Path C:DSCCertificate

Let’s go ahead and run it:

Now, that’s a lot of info because we’re using the -Verbose switch on the Start-DscConfiguration cmdlet. If you look closely at the blue section, you’ll see DSC doing this:

• Locate the CA
• Call certutil to ping the CA to check it’s online
• Check for a certificate which matches the names we’ve requested
• Create a certificate request
• Install the certificate

At the end, in white, Test-DscConfiguration runs and states that our target machine is in the desired state so let’s check we have the correct certificate installed on our target machine:

Connect to remote PowerShell on the target computer:

Enter-PSSession contchidsc01

Open up the local computer certificate store:

cd Cert:LocalMachineMy

List the certificates:

dir

Now we have our certificate installed!

Conclusion

We’re learning quite a lot about DSC. We’re now able to find the DSC resources we need to do almost anything we need to do and we know how to find the documentation, download the modules and use the included DSC resources. So far, we’ve been pushing configurations using Start-DscConfiguration but in the upcoming posts, we’ll look at configuring SMB or HTTPS pull servers.