Configure WinRM to execute PowerShell Script on a remote Azure machine with ARM

Microsoft has introduced Azure Resource Manager (ARM) to make it easier for managing Azure resources. It creates Resource Groups which are a collection of cloud services of virtual machines, virtual networks, network interfaces, network security rules, public IP address, storage accounts, etc. A virtual machine added to the resource group can be accessed in the build or release management task using a combination of the name of the resource group and fully qualified name (FQDN) of the virtual machine.

WinRM is a service that allows remote execution of PowerShell scripts over the HTTP or HTTPS connection. For running a PowerShell script from a remote machine, the virtual machine where the script has to run (we will call it as host) has to have WinRM listeners on HTTP and HTTPS protocols. These listeners use the port 5985 and 5986 respectively. Build service and Release Management service of TFS 2015 and Visual Studio Team Services (VSTS) have many tasks that use the WinRM service to execute PowerShell script on a remote machine in Azure that is under ARM.

Figure 1: Release Management task that runs a PowerShell script on target machine

A virtual machine that is created in the resource group of ARM can be easily configured to have listeners for WinRM service. WinRM Service listeners are already installed on those virtual machines. Those listeners are not accessible because, in Azure, communication endpoints for the ports 5985 and 5986 are not created by default for those VMs. For a VM that is in the workgroup, it is essential to bind the WinRM service to secure transport that uses HTTPS protocol. To enable access to WinRM HTTPS listener, we need to create an Inbound Rule to allow traffic on port 5986. For VMs under the Resource Group in ARM, port 5986 is already opened in the firewall.

Figure 2: Create Inbound Rule for Port 5986

When we configure a task that uses WinRM for executing a PowerShell script, it is expected to configure WinRM listener for HTTPS transport protocol on the target machine. The Fully Qualified Domain Name (FQDN) of the target machine is used to set up these tasks. Unfortunately, when executing such a task, it fails with an error “The SSL certificate contains a common name (CN) that does not match the hostname”. This error occurs because the WinRM listener configured on the target server does not have the SSL certificate that has the FQDN in the name. We can check the WinRM listeners in the configuration on the machine that is created by ARM by running the following command in the developer command prompt.

winrm e winrm/config/listener

Running this command may show the following configuration:

Figure 3: WinRM Listeners (as original)

You may observe that for a listener configured for HTTPS, the Hostname parameter has a value that is the IP address of the machine and not the FQDN. Let us now check if we do have an SSL certificate that has an FQDN as CN. For that run the command mmc.exe and select the snap-in for Certificates and select Computer account as the scope.

Figure 4: Certificates Snap-In to MMC

In the MMC snap-in for certificates, we will notice that no certificate is created for FQDN but there is one created for IP address.

Figure 5: Certificates on Target machine

What we need to do is to create a certificate for FQDN and bind it to HTTPS transport protocol WinRM listener. Let us now check the FQDN of the target virtual machine. In the Azure portal, if we select the virtual machine and then Public IP Address / DNS Name, it will show us the FQDN as DNS name if that is configured. You can configure it if not already configured.

Figure 6: FQDN of Target Machine

Our next step is to create a certificate on the target machine that has FQDN as the hostname. For that, we can run a PowerShell cmdlet on that machine.

New-SelfSignedCertificate –DnsName ssrmdvm3.southeastasia.cloudapp.azure.com –CertStoreLocation Cert:\LocalMachine\My

This step will create a self-signed certificate for testing purposes. The output of the command will show a thumbprint of the certificate. That thumbprint is a 40 digit number.

Figure 7: New Self Signed Certificate and its thumbprint

We will now delete the existing WinRM listener that is linked to SSL certificate with IP address and create a new listener that is linked to FQDN. To do so, we will execute two cmdlets in succession:

winrm delete winrm/config/listener?Address=*+Transport=HTTPS

winrm create winrm/config/listener?Address=*+Transport=HTTPS ‘@{Hostname=ssrmdvrm3.southeastasia.cloudapp.azure.com”; CertificateThumbprint=”Copy the thumbprint from earlier cmdlet output”;port=”5986”}’

Figure 8: Delete old listener and Create new listener

Figure 9: New WinRM listener created

If we now check the listeners of WinRM by running the following command:

winrm e winrm/config/listeners

..we will see that Hostname of the HTTPS listeners reflects the FQDN.

Figure 10: WinRM Listener Configuration (new)

If we run the same release with the task that needs to execute a PowerShell script remotely using WinRM, it works without any error.

This article has been editorially reviewed by Suprotim Agarwal.

C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.

We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).

Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.

Click here to Explore the Table of Contents or Download Sample Chapters!

Author

Subodh is a Trainer and consultant on Azure DevOps and Scrum. He has an experience of over 33 years in team management, training, consulting, sales, production, software development and deployment. He is an engineer from Pune University and has done his post-graduation from IIT, Madras. He is a Microsoft Most Valuable Professional (MVP) - Developer Technologies (Azure DevOps), Microsoft Certified Trainer (MCT), Microsoft Certified Azure DevOps Engineer Expert, Professional Scrum Developer and Professional Scrum Master (II). He has conducted more than 300 corporate trainings on Microsoft technologies in India, USA, Malaysia, Australia, New Zealand, Singapore, UAE, Philippines and Sri Lanka. He has also completed over 50 consulting assignments - some of which included entire Azure DevOps implementation for the organizations.

He has authored more than 85 tutorials on Azure DevOps, Scrum, TFS and VS ALM which are published on www.dotnetcurry.com.Subodh is a regular speaker at Microsoft events including Partner Leadership Conclave.You can connect with him on LinkedIn .