Skip to content

Job Execution Configuration

12Port utilizes Windows Remote Management (WinRM) to execute PowerShell scripts remotely on Windows hosts. This allows the application to manage systems, publish policies, automate tasks, and interact with the Windows environment securely and efficiently.

WinRM is a Windows-native service that allows remote management over the WS-Management protocol, supporting both HTTP and HTTPS transport. While HTTP (default) provides ease of setup, HTTPS can be optionally configured to ensure secure communication.

This document outlines how to configure 12Port and Windows hosts to enable remote PowerShell execution using WinRM over HTTP (default) or WinRM over HTTPS (secure/optional). Only one configuration is required for executing jobs; either WinRM (HTTP) or secure WinRM (HTTPS).

Requirements

  • Windows host with PowerShell 5.1 or later (or PowerShell Core)
  • Administrator privileges on the target system
  • Access to port 5985 (HTTP) and/or 5986 (HTTPS)
  • Credentials, for use by 12Port, that has membership in the host's local Administrators or Remote Management Users group.

Configure WinRM (HTTP)

To setup WinRM on a Windows host system use the following procedure:

Windows Host Configuration

Steps:

  1. Open PowerShell as Administrator on the remote (target) Windows host.

  2. Run the following command:

    winrm quickconfig

  3. When prompted by the command:

    • Confirm starting the WinRM service.
    • Confirm creating a listener on HTTP.
    • Confirm creating a firewall exception.

  4. (Optional) Verify the listener was created:

    winrm enumerate winrm/config/listener

This command should complete in its entirety without any reported errors. If errors occur, please try the configuration again before proceeding.

12Port Configuration

Create a new Asset in 12Port Horizon that will be used to manage this remote (target) Windows Host using WinRM.

Steps:

  1. Login to Horizon with an account that can create new assets.
  2. Navigate to Database > Assets and select a container in which the new asset will be located.

  3. Use the Add > Windows Host menu to create your new asset. From the Add Asset page, populate the parameter fields as followed:

    • Name: enter a recognizable, and recommended, unique name for this new asset.
    • Description: optionally, enter a description value.
    • Host: enter the fully qualified domain name or IP address of this remote (target) Windows Host system.
    • User: enter the domain or local user account of the account that will be used to authenticate the remote PowerShell command (format domain\user or local\user). The supplied account must have membership on the host's local Administrators or Remote Management Users group.
    • Password: enter the password of this account.
    • Tags: optionally, assign tags to this asset.

  4. Click the Save button to complete the creation of this new asset.

Note

The Asset Type includes an additional hidden field that can optionally be configured if the default port (5985) is not being used by WinRM. Unhide the Management Port field and use this parameter to define your custom port number for WinRM.

After the asset is created, use the Execute > Windows Status option to test connectivity. After approximately 30-60 seconds this job should complete and be listed as Completed from the Reports > Job report of this asset. The transport protocol used will be displayed at the end of the job's Result field. In this example, WinRM:HTTP is shown indicating the job execution used WinRM (HTTP).

Job Execution using WinRM (HTTP)

If the job fails, refer to our Job Execution Troubleshooting Guide for a list of common issues and solutions.

 

(Optionally) Configure Secure WinRM (HTTPS)

To setup Secure WinRM (HTTPS) on a Windows host machine use the following procedure.

Note

Secure WinRM requires installing an SSL certificate. If this is not available or you don't feel comfortable, we recommend to configure WinRM (HTTP) as described in the previous section.

Windows Host Configuration

Steps:

  1. Install an SSL certificate on the remote host:
    • The certificate must be placed in the Local Machine > Personal store.
    • It must have a private key and support Server Authentication.
    • The hostname (or FQDN) used to connect must match the Common Name (CN) or Subject Alternative Name (SAN) of the certificate.

  2. Find the certificate thumbprint, replacing "your-hostname" with part or all of the CN or SAN name you used when creating the certificate.

    Get-ChildItem -Path Cert:\LocalMachine\My | 
Where-Object { $_.Subject -like "*your-hostname*" } | 
Select-Object Subject, Thumbprint

  3. Create the HTTPS listener, replacing "your-hostname" with part or all of the CN or SAN name you used when creating the certificate and THUMBPRINT with the exact value from the previous step (no spaces).

    winrm create winrm/config/Listener?Address=*+Transport=HTTPS `
@{Hostname="your-hostname"; CertificateThumbprint="THUMBPRINT"}

  4. Open the firewall port 5986:

    New-NetFirewallRule -DisplayName "WinRM HTTPS" -Name "WinRM-HTTPS" `
-Profile Any -Direction Inbound -Action Allow -Protocol TCP -LocalPort 5986

  5. (Optional) Disable the HTTP listener if only Secure WinRM (HTTPS) should be allowed:

    winrm delete winrm/config/Listener?Address=*+Transport=HTTP

Each command should complete without any reported errors. If errors occur, please try the configuration again before proceeding.

12Port Configuration

Create a new Asset in 12Port Horizon that will be used to manage this remote (target) Windows Host using Secure WinRM.

  1. Login to Horizon with an Administrator or Asset Type Manager role.
  2. Navigate to Management > Asset Type and use the Edit option for the Windows Host asset type.
  3. In the Asset Type Fields section, locate the Port Security field and use the option Actions > Unhide.
  4. Click the Save button to complete the asset type update.
  5. Navigate to Database > Assets and select a container in which the new asset will be located.

  6. Use the Add > Windows Host menu to create your new asset. From the Add Asset page, populate the parameter fields as followed:

    • Name: enter a recognizable, and recommended, unique name for this new asset.
    • Description: optionally, enter a description value.
    • Host: enter the fully qualified domain name of this remote (target) Windows Host system. The hostname should match the Common Name (CN) or Subject Alternative Name (SAN) of the issued certificate.
    • Port Security: click the switch to enable secure WinRM (HTTPS) for this asset.
    • User: enter the domain or local user account of the account that will be used to authenticate the remote PowerShell command (format domain\user or local\user). The supplied account must have membership on the host's local Administrators or Remote Management Users group.
    • Password: enter the password of this account.
    • Tags: optionally, assign tags to this asset.

  7. After the field parameters are populated, click the Verify Trust button on the upper right. Review and confirm or Import the required certificate from this remote Windows Host to 12Port.

  8. Click the Save button to complete the creation of this new asset.

Note

The Asset Type includes two additional hidden field that can optionally be configured.

- Verify Certificate: Unhide and enable this parameter if host verification (via the Verify Trust button) is required and if not verified, the connection will fail. If disabled, the certificate will not be verified.
- Verify Host: Unhide and enable this parameter if the Asset's Host must match the hostname of the issued certificate and if there is a mismatch, the connection will fail. If disabled, this hostname match will not be verified. Note, if enabling Verify Host we recommend also enabling Verify Certificate to ensure the entire authenticity of the issued certificate.

Note

The Asset Type includes an additional hidden fields that can optionally be configured if the default port (5986) is not being used by WinRM. Unhide the Management Port field and use this parameter to define your custom port number for WinRM.

After the asset is created, use the Execute > Windows Status option to test connectivity. After approximately 30-60 seconds this job should complete and be listed as Completed from the Reports > Job report of this asset. The transport protocol used will be displayed at the end of the job's Result field. In this example, WinRM:HTTPS is shown indicating the job execution used WinRM (HTTPS).

Job Execution using WinRM (HTTPS)

If the job fails, refer to our Job Execution Troubleshooting Guide for a list of common issues and solutions.

After completing the above steps, your remote Windows host will be configured to accept PowerShell commands over WinRM using either HTTP (default) or HTTPS (secure). Horizon can now connect to the host, authenticate using supported credentials, and perform its operations using remote PowerShell sessions.

When using HTTPS, make sure that Horizon trusts the certificate using the Verify Trust option available from the asset, especially when using a self-signed certificate.

Need Help?

If you're encountering issues with WinRM connections, refer to our Job Execution Troubleshooting Guide for a list of common issues and solutions.