Replace the WinRM HTTPS Listener Certificate

WinRM over HTTPS listens on TCP 5986 by default. The HTTPS listener stores the certificate thumbprint and the hostname itself, so importing a new certificate does not change what PowerShell remoting presents - the listener has to be pointed at it.

Before you beginCopy Anchor Link

• Make sure you have a way in that does not depend on the HTTPS listener: a local or virtual-machine console, out-of-band management (iLO, iDRAC), or the WinRM HTTP listener on port 5985. Test it before you start. A wrong thumbprint or hostname breaks the HTTPS listener, and a remote session over it cannot fix itself.
• Microsoft's requirements for the certificate:
  • in Certificates (Local Computer) > Personal, with a private key,
  • Server Authentication in the Enhanced Key Usage,
  • the listener's hostname in the CN or exactly as one of the SANs,
  • not expired, not revoked and not self-signed.

Step-by-step certificate replacementCopy Anchor Link

1. Show the current listener and note its settings, especially the CertificateThumbprint - you need it for a rollback:

   Copy Text

   winrm enumerate winrm/config/listener
   Get-ChildItem WSMan:\localhost\Listener

2. Import the PFX into the Local Computer Personal store, next to the old certificate, and read the new thumbprint:

   Copy Text

   $cert = Import-PfxCertificate -FilePath C:\secure\server.pfx `
     -CertStoreLocation Cert:\LocalMachine\My -Password (Read-Host -AsSecureString)
   $cert.Thumbprint

3. Point the existing HTTPS listener at the new certificate:

   Copy Text

   $selector = @{Address="*";Transport="HTTPS"}
   $values = @{Hostname="server.example.com";CertificateThumbprint="<thumbprint>";Port="5986"}
   Set-WSManInstance -ResourceURI winrm/config/Listener -SelectorSet $selector -ValueSet $values

   Keep the address, hostname and port the listener showed in step 1; Hostname must be a name in the certificate. If there is no HTTPS listener yet, New-WSManInstance with the same selector and values creates one, or run winrm quickconfig -transport:https, which picks a matching certificate itself.

4. Before you close your current session, open a second connection over HTTPS (see Verify). Only when that works, close the first. The WinRM service does not need a restart. If you also changed the port, allow it in Windows Firewall.

Verify the new certificateCopy Anchor Link

winrm enumerate winrm/config/listener
Test-WSMan -ComputerName server.example.com -UseSSL -Port 5986
Enter-PSSession -ComputerName server.example.com -UseSSL -Port 5986

The thumbprint in the listener output must match the new certificate. Run the tests from a remote client that trusts the chain, not only locally.

RollbackCopy Anchor Link

Set the old CertificateThumbprint from step 1 with the same Set-WSManInstance command - over the other way in, if the HTTPS listener no longer answers. This requires the old certificate to still be in the store and valid.

Common problemsCopy Anchor Link

• Error 0x80338115 - "Cannot create a WinRM listener on HTTPS because this machine does not have an appropriate certificate": the certificate's CN or SAN does not match the hostname, it lacks Server Authentication, it is expired, revoked or self-signed, or it is not in the Local Computer store.
• Several suitable certificates are installed and the listener uses a different one than intended - compare the thumbprint in winrm enumerate winrm/config/listener.
• Remote access was lost because the listener was changed over the same HTTPS session, without a tested second way in - use the console or HTTP listener to repair it.
• Port 5986 or a custom port is blocked.

Automating certificate replacement with aethercertCopy Anchor Link

The aethercert WinRM target imports the certificate and replaces the local HTTPS listener using the configured hostname and port.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.

SourcesCopy Anchor Link

• Microsoft Learn: configure WinRM for HTTPS
• Microsoft Learn: WinRM installation and configuration