vRO - Integrating Windows PowerShell

To run PowerShell commands using vRO, you need to integrate PowerShell hosts with vRO's PowerShell plugin. The plugin serves as a bridge between vRO and the PowerShell execution environment. It facilitates communication with PowerShell on remote hosts by leveraging the Windows Remote Management (WinRM) protocol. WinRM is a feature of Windows that allows for secure and efficient management of remote systems, and it enables vRO to send commands and scripts to remote PowerShell instances.

TLDR: To enable your PowerShell host to handle WinRM requests from vRO, you must set up a listener. WinRM offers two types of listeners: HTTP and HTTPS, each utilizing different port numbers for obvious reasons—5985 and 5986, respectively. IYou then integrate the listener with vRO using the PowerShell Plugin.

The process described in this blog was carried out on Windows 2022 with PowerShell 7.4.6 installed, and PowerShell remoting was activated during the installation.

There are two parts to the entire process:

• Preparing the PowerShell Host

• Integrating PowerShell Host with vRO

Part 1 : Preparing the PowerShell Host

Proper configuration of WinRM on the Powershell host is crucial, as it must be enabled and configured to accept remote PowerShell commands. This involves setting up appropriate firewall rules, configuring listeners, and ensuring that the necessary permissions are granted to the user accounts that will be executing the commands.

The procedure outlined below can be used to set up an HTTPS listener on a PowerShell host for WinRM:

1. WinRM can be setup with a default configuration by running the following command:

   winrm quickconfig

2. If WinRM is already configured on the server, you could run a ’winrm get’ commands to fetch current configuration:

winrm enumerate winrm/config/listener

2. 

3. Run the following command for an extented configuration infromation.

winrm get winrm/config

From the screenshot above you could tell that WinRM is already enabled. And for the purposes of this blog, we will be using Basic authentication (username/passsword) for the Orchestrator plugin to connect with the PowerShell host. However, you can tell from the screenshot that Basic Authentication is set to false. Our next step will be to enable to Basic authentication.

4. To enable Basic Authentication, run the following command:

   winrm set winrm/config/service/auth ‘@{Basic=“true”}’

2. 

5. If you remember from the output at step-2, the current transport listerner is ‘HTTP’. Our next step is to enable HTTPS listener. However, before enabling a HTTPS listener, WinRM requires you to install a server certificate for your PowerShell host.

6. In most cases it is recommended to procure a certificate from a Certificate Authority trusted by your organization. Alternatively, you could also generate and install a self-signed certificate using the following command and make a note of the THUMBPRINT generated.

New-SelfSignedCertificate -CertStoreLocation cert:\localmachine\my -DnsName ("fqdn of the server", "hostname of the server") -NotAfter (get-date).AddYears(5) -Provider "Microsoft RSA SChannel Cryptographic Provider" -KeyLength 2048

7. Once done, use MMC to go to :  Console Root | Certificates(Local Computer) | Personal | Certificates

   

8. Copy the certificate to : Console Root | Certificates (Local Computer) | Trusted Root Certification Authorities | Certificates

   

9. Make a note of the Thumbprint of the cerfificate that was created earlier.

   

10. Delete the existing HTTP listeners if any using the following steps:

        (a) Lookup for any existing listeners on the machine

          winrm get winrm/config/Listener?Address=*+Transport=HTTPS

        (b) Run the delete command to delete the listener

          winrm delete winrm/config/Listener?Address=*Transport=HTTPS

        (c) Run a winrm get again to verify if the listerner has been deleted.

    
    

11. Create a new WinRM HTTPS listener using following command syntax:

winrm create winrm/config/Listener?Address=*+Transport=HTTPS `@{Hostname=“FQDN of the PS host”;CertificateThumbprint=“xxxxxxxxxxxx”}`

12. Run a winrm get again to verify if the listerner has been created.

    

13. Add a local firewall rule for WinRM on the Powershell Host, using the following sample command syntax.

C:\> netsh advfirewall firewall add rule name="WinRM" dir=in action=allow protocol=TCP localport=5986`

C:\> netsh advfirewall firewall show rule name=WinRM

14. Run the following commands to test the connection:

Syntax: 
winrs -r:https://fqdn:port_number -u username <batch_command>    
Example:
winrs -r:https://pshost01.vdescribed.lab:5986 -u vdescribed\psadmin hostname

The following screenshot shows a connection test from a jumpbox “jumpbox01” to the powershellhost “corepshost01”

Note: If you get SSL errors, you will need to import the powershell host’s certificate into the Trusted Authorities on the remote sever you running the test from.

The next step in the integration process is to add the PowerShell (PS) host to the vRealize Orchestrator (vRO). See Part-2 for the procedure.

---

Part 2: Integrating PowerShell Host with vRO

In Part-2 we integrate the PowerShell host with vRO. This step enables vRO to communicate with the PowerShell environment, allowing for the execution of scripts and automation tasks directly from the vRO interface. Accomplishing this involves running a specific plugin workflow designed for the purpose of adding the PowerShell host.

1. Logon to Aria Automation and swith to Orchestrator

2. Navigate to Library | Workflows and filter for the PowerShell plugin and locate the “Add a PowerShell host” workflow.

   

3. Use the vertical elipses to “Run” the worflow

   
   

   

4. At the PowerShell Host tab of the “Add a PowerShell Host” workflow page supply a Name, Host/IP and set the port to 5986.

   

5. In the Host Type tab, set the remote host type to “WinRM”, transfer protocol to “HTTPS”, choose to accept all certificates and set the Authentication to “Basic”.

   

6. In the User Credentials tab, set the session mode to “Shared Session” and supply the user credentials for the connection. It is recommended to use a service account for this purpose. For now we will be using the local “Administrator” account on the PowerShell host.

   

7. In the Advanced Options tab, leave everything to the default. The Shell Code Page is set to IBM437 by default. Once done, click RUN.

   
   

   

8. Let the workflow run to completion and finish successfully.

   

9. Once added, it should show up in the vRO's inventory. Naviate to Administration | Inventory and expand the PowerShell plugin enty to find the newly added PowerShell host.

   

10. Now, vRO does have a workflow to validate the PowerShell host that you added.  Go back to Library | Workflows and locate “Validate a Powershell host”

    

11. Run the workflow and use the tree-picker to select the PowerShell hosts from the inventory and click RUN.

    

12. Let the workflow run to completion and finish successfully.

    

13. The plugin does come with a buch of additional workflows that can be used to execute commands/scripts on the PowerShell host. We will run one of those to verify if the plugin can execute commands.

14. Go to Library | Workflows and locate “List Directory content”

    

15. Run the workflow and use the tree-picker to select the PowerShell host you added and specify a directory to list contents and click RUN and wait for it to complete sucessfully.

    

    

    This confirms that the VRO plugin can connect and execute commands on the PowerShell host, indicating a sucessfull integration.

Once the integration is in place, you can leverage the capabilities of vRO to automate various tasks across your infrastructure. For instance, you can create workflows that execute PowerShell scripts to manage system configurations, deploy applications, gather system information, or perform routine maintenance tasks. Aria Orchestrator provides a user-friendly interface to define these workflows, allowing you to specify inputs, outputs, and error handling mechanisms that enhance the reliability and efficiency of your automation processes.