Creating WS-Man Listeners with DSC
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!
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.
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:
[sourcecode language=“powershell”] Install-Module -Name cWSMan -MinimumVersion 1.0.0.0 [/sourcecode]
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.
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:
[sourcecode language=“powershell”] 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 [/sourcecode]
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:
[sourcecode language=“powershell”] 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 [/sourcecode]
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:
[sourcecode language=“powershell”] 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 [/sourcecode]
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.