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.

Advertisements

Install an SSL WS-Management Listener with GPO

Introduction

One of the things I like to do when ever I install a new server is to enable an HTTPS/SSL WS-Management Listener on it so that I can disable the more insecure HTTP WS-Management listener. For more information on WS-Management Listeners see this MSDN article.

There are many benefits to using a secure HTTPS/SSL WS-Management Listener:

  1. Security – the communication channel between client and server is encrypted using SSL.
  2. Authentication – the server is authenticated to the client so you can trust you’re talking to the server you think you’re talking to.

The downside to this is that you need a valid and trusted server authentication certificate on the server to enable this – but if you have a PKI then this is no big deal as you’ll probably have certificate autoenrollment enabled. If you don’t have a PKI, then you should look into installing one.

Installing these listeners manually is fairly straight forward and requires only a single command:

New-WSManInstance -ResourceURI winrm/config/Listener `
-SelectorSet @{Address='*';Transport="HTTPS"} -ValueSet @{Hostname="SERVER01.CONTOSO.COM";CertificateThumbprint="09 49 93 24 53 81 32 16 b7 44 8b 47 ca af 56 3a ef 9f 10 2d"}

All you need to do is enter the appropriate hostname and certificate thumbprint for a server authentication certificate that exists on the server. But who wants to do this manually, right?

Installing with GPO

The slightly tricky part of installing this automatically onto your servers with a GPO is detecting which certificate to use. The certificate must:

  • exist in the local computer personal certificate store.
  • have an Extended Key Usage of Server Authentication.
  • be issued by a CA trusted by any client connecting to the server.
  • The Subject must contain a Common Name that contains either the FQDN computer name or the flat computer name (e.g. CN=SERVER1.CONTOSO.COM or CN=SERVER1).

It is easy to ensure a certificate meets these criteria by using a GPO enabling certificate autoenrollment for computer certificates and that the Computer autoenrollment certificate template will create certificates meeting these requirements. See this page for some basic information on certificate autoenrollment. There are some much more detailed instructions on this around the net if you’re happy to search.

Once you’ve ensured all your computers have been issued such a certificate you would normally need to lookup the certificate on each computer and get the certificate thumbprint and execute the command I showed earlier. This would be a complete pain on any more than 10 computers, and probably pure insanity at a lot of facilities.

So, I put together the following PowerShell commands that could be used to automatically pull the certificate thumbprint for an appropriate certificate:

[String] $Issuer = 'CN=CONTOSO.COM Issuing CA, DC=CONTOSO, DC=COM'
[String] $HostName = [System.Net.Dns]::GetHostByName($ENV:computerName).Hostname
[String] $Thumbprint = (get-childitem -Path Cert:\localmachine\my | Where-Object { 
		        ($_.Extensions.EnhancedKeyUsages.FriendlyName -contains 'Server Authentication') -and
		        ($_.IssuerName.Name -eq $Issuer) -and
		        ($HostName -in $_.DNSNameList.Unicode) -and
                ($_.Subject -eq "CN=$HostName") } | Select-Object -First 1
            ).Thumbprint

All you’d need to set was the Issuer to whatever the Distinguished Name of your issuing CA is – which should be the same for all computers. This simplifies things a lot because the same code could be run on any computer and should always return the correct thumbprint.

The next step was to put it into a script where you could just pass the Distinguished Name of the issuing CA as a parameters. I did this and also added some other optional parameters and uploaded the result to Microsoft Script Center. So you can download this script and put it into a GPO Startup Script:

Installing an HTTPS WS-Management Listener with GPO

Installing an HTTPS WS-Management Listener with GPO

The script is actually a little bit smarter than the above command. If a certificate with a subject can’t be found that matches the FQDN of the computer it will automatically look for one that just uses the flat computer name. You can control this behavior by setting the DNSNameType parameter.

There are some other optional parameters that control other the behavior of the script as well:

DNSNameType

The allowed DNS Name types that will be used to find a matching certificate. If set to FQDN then the script will only try to find a certificate with a subject matching the FQDN of the computer. If set to ComputerName it will only match on the computer name of the computer. By default this is set to Both which will try to match on FQDN first and then ComputerName if it can’t find one matching the FQDN.

MatchAlternate

The certificate found must also have an alternate subject name containing the DNS name found in
the subject as well. This places additional restrictions on the certificate that is used, but is not usually required. This defaults to False.

Port

This parameter lets you specify an alternate port to install the HTTPS/SSL listener on. If you don’t specify it, it will use the default port of 5986.

Don’t Forget your Firewall

It is important to remember that by default this listener is installed onto port 5986, which is not usually open inbound. So you’ll want to add a firewall rule to ensure this port can be reached – another job for GPO. You could even add this setting into the GPO that installs the HTTPS/SSL listener.

Installing with DSC

In theory it should be possible to adapt this code to run in a DSC Script Resource. I haven’t tried this yet, but you can be assured that I will fairly soon. If there was some interest in this I could convert it into a proper DSC Resource (unless there was one already – I haven’t checked). If you are interested, let me know.

Links

If you want to make a copy of the repository, you’ll find it here:

https://github.com/PlagueHO/WSManGPOTools

Right, that is me out for another Sunday. Thanks for reading.