WinRM Client Certificate Authentication : Step-By-Step Setup And Configuration Guide

This repo demonstrates how to create certificates for WinRM/WSMan client certificate authentication and how to configure Windows to setup the service side to allow those certificates for client authentication.

It has some Ansible playbooks that can be used to do all the necessary steps plus some standalone scripts and background information to help you understand how certificate authentication works and is configured.

Background

WinRM authentication is typically done through the Negotiate protocol which attempts to use Kerberos authentication before falling back to NTLM.

It is possible to use client certificates through the TLS X.509 client certificate authentication but the documentation around this is hard to come by and hard to understand.

This repo will attempt to show how to both generate those certificates and how to configure the Windows host to use them for authentication.

It will also show how those certificates can be used in Ansible to perform certificate authentication.

Please keep in that certificate authentication does have its downsides such as:

• it can only be mapped to a local Windows user, no domain accounts
• the username and password must be mapped to the certificate, if the password changes, the cert will need to be re-mapped
• an administrator on the Windows host can retrieve the local user password through the certificate mapping
• the HTTP libraries used by psrp and winrm do not support
  • encrypted private keys, they must be stored without encryption
  • certs and private keys stored as a var, they must be a file

Usually these points are blockers (the last one especially) but if you are still interested then read on.

Requirements

• Windows host with a HTTPS WinRM listener configured
• Ansible collections
  • ansible.windows – Used to configured the Windows host
  • community.crypto – Used in setup_certificate.yml
• Python libraries winrm and psrp for testing the connection

To install the Python libraries we can run:

python3 -m pip install pypsrp winrm

To install the required collections run

ansible-galaxy collection install -r requirements.yml

If you are not using setup_certificate.yml to generate the certificates, then community.crypto will not be needed.

How To Run

Before running we need to add in the inventory details for our Windows host. Edit inventory.ini and add the Windows host hostname/IP under the [windows] section. Also set the ansible_user and ansible_password value under the [windows:vars] section. We can verify that it worked by running ansible -i inventory.ini windows -m ansible.windows.win_ping.

Once the inventory has been setup we run the following playbooks with the CERT_USER set to the Windows user we want to create that’s mapped to the certificate:

CERT_USER=AnsibleCertUser
ansible-playbook -i inventory.ini setup_certificate.yml -e username=$CERT_USER
ansible-playbook -i inventory.ini setup_windows.yml -e username=$CERT_USER

For more information click here.