Creating WS-Man Listeners with DSC

Introduction

After my last post showing how to create an SSL/HTTPS listener using GPO, I thought this might be a good fit for a Desired State Configuration Resource. So after a rainy Saturday morning coding I had it working nicely.

You might ask “what is the point of adding HTTPS/SSL WS-Man Listeners when HTTP WS-Man Listeners are usually enabled by default”? Well, first off, it ensures you’re going to be connecting to the server you actually think you’re connecting to. This is pretty important and helps protect against DNS poisoning and man-in-the-middle attacks. It also means you don’t have to set the WS-Man client trusted hosts setting on your client machines to bypass host name checking for your servers:

No more of this!

No more of this!

HTTPS/SSL and Certificates

This DSC Resource essentially allows you to create, configure and remove HTTP and HTTPS/SSL WS-Man Listeners. That is pretty much it.

However, the most common use is going to be creating an HTTPS/SSL listener by automatically detecting the appropriate certificate to use. It uses the exact same method of doing this as described in this post, so I won’t go over it here. But essentially, all you need to do is provide the full name of the Issuing CA that will have issued the certificate to the computer. The certificate would normally have been created and assigned to each server using Certificate Autoenrollment using an Active Directory Certificate Services PKI and GPO, but this is not required – you could use any certificate enrollment method.

Installing the Resource

The first thing that needs to be done is installing the cWSMan Module. If you’re using WMF 5.0 you can get this directly from the PowerShell Gallery by running this command:

Install-Module -Name cWSMan -MinimumVersion 1.0.0.0

If you’re using WMF 4.0 then you’ll need to get this from the Microsoft Script Center. But of course, you’re using WMF 5.0 right?

Once it is installed you can integrate it into your DSC Scripts.

Using the Resource

The most likely thing you’re going to want to do is install an HTTPS/SSL Listener. To do that all you need to do is something like this:

configuration Sample_cWSManListener_HTTPS
    {
    Import-DscResource -Module cWSMan

    Node Server01
    {
        cWSManListener HTTPS
        {
            Transport = 'HTTPS'
            Ensure = 'Present'
            Issuer = 'CN=CONTOSO.COM Issuing CA, DC=CONTOSO, DC=COM'
        } # End of cWSManListener Resource
    } # End of Node
} # End of Configuration

This would install an HTTPS/SSL Listener onto the default port of 5986 using a certificate that was issued by CN=CONTOSO.COM Issuing CA, DC=CONTOSO, DC=COM. There really is nothing to it – it is actually more fiddly getting your PKI set up than doing this part.

You can also configure the port and address to bind the HTTPS/SSL Listener to by passing the port and address parameters as well:

configuration Sample_cWSManListener_HTTPS
    {
    Import-DscResource -Module cWSMan

    Node Server01
    {
        cWSManListener HTTPS
        {
            Transport = 'HTTPS'
            Ensure = 'Present'
            Issuer = 'CN=CONTOSO.COM Issuing CA, DC=CONTOSO, DC=COM'
            Port = 7000
            address = '192.168.1.55'
        } # End of cWSManListener Resource
    } # End of Node
} # End of Configuration

If you don’t provide the port and address parameters they default to 5986 (or 5985 for HTTP listeners) and ‘*’ respectively.

You can also use this resource to remove an HTTP or HTTPS listener. For example you might want to remove the default HTTP listener so that it can’t be used once your HTTPS listener has been created. To do that:

configuration Remove_cWSManListener_HTTP
    {
    Import-DscResource -Module cWSMan

    Node Server01
    {
        cWSManListener HTTP
        {
            Transport = 'HTTP'
            Ensure = 'Absent'
        } # End of cWSManListener Resource
    } # End of Node
} # End of Configuration

Feedback

If you’re interested in contributing to this resource, providing feedback or raising issues or requesting features, please feel free (anything is appreciated). You’ll find the resource GitHub repository here where you can fork, issue pull requests and raise issues/feature requests.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s