Configuring WinRM for PowerShell

WinRM (Windows Remote Management) is a crucial component for enabling PowerShell communication. This configuration lays the foundation for executing PowerShell scripts remotely. Ensure that WinRM is properly configured before proceeding to CredSSP setup.

Overview

Secret Server relies on Windows Remote Management (WinRM) components to run PowerShell scripts. This requires configuration on the Secret Server Web server and any distributed engines. By default, Secret Server uses http://localhost:5985/wsman as the WinRM endpoint. The endpoint URI can be seen under Admin > Distributed Engine > Local, in the Advanced site configuration section. At the moment, we only support running PowerShell scripts on localhost. If you are new to PowerShell Remoting please review PowerShell Remoting Security Considerations.

Note that your system should be running Windows Server 2012 or later, have the Administrative access to the server, and there should be network connectivity between the client and server.

Standalone Configuration

By default WinRM uses Kerberos for authentication. Since Kerberos is not available on machines that are not joined to the domain, HTTPS is required for secured transport of the password. Only use this method if you are going to run scripts from a Secret Server Web server or distributed engine that is not joined to the domain.

WinRM HTTPS requires a local computer "Server Authentication" certificate with a CN matching the hostname that is not expired, revoked, or self-signed. A certificate would need to be installed on each endpoint Secret Server or the engine manages.

To create a new listener use the command New-WSManInstance to create a new WSMan instance for managing remote connections.

New-WSManInstance - ResourceURI winrm/config/Listener -SelectorSet @{Transport=HTTPS} -ValueSet @{Hostname="HOST";CertificateThumbprint="XXXXXXXXXX"}

Domain Joined Configuration

Run PowerShell as an Administrator and execute:

Enable-PSRemoting

See Enable-PSRemoting for more information.

This command performs the following steps:

  • Runs the Set-WSManQuickConfig cmdlet, which performs the following tasks:

    • Starts the WinRM service
    • Sets the startup type on the WinRM service to Automatic
    • Creates a listener to accept requests on any IP address
    • Enables a firewall exception for WS-Management communications
    • Registers the Microsoft.PowerShell and Microsoft.PowerShell.Workflow session configurations, if it they are not already registered
    • Registers the Microsoft.PowerShell32 session configuration on 64-bit computers, if it is not already registered
    • Enables all session configurations
    • Changes the security descriptor of all session configurations to allow remote access.

  • Restarts the WinRM service to make the preceding changes effective.

Verifying Listeners

Confirm the listener:

Copy 
Get-WSManInstance -ResourceURI winrm/config/listener -SelectorSet @{Address="*";Transport="http"}

The output should reflect the newly configured listener with Enabled : true

Additional Considerations

Ensure that the account running WinRM and connecting to the target machine has the permissions to access that machine over the network. Configure the policy value for Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment > Access this computer from the network to include the service account or user account that will need access to this computer over the network via WinRM.

  • By default two BUILTIN groups are allowed to use PowerShell Remoting as of v4.0: Administrators and Remote Management Users.

    (Get-PSSessionConfiguration -Name Microsoft.PowerShell).Permission

  • Sessions are launched by Secret Server under the user's context, which means all the same security controls and policies apply within the session.
  • See Tracking, Detecting, and Thwarting PowerShell-based Malware and Attacks (Trend Micro) for additional security considerations.
  • Your environment may already be configured for WinRM. If your server is already configured for WinRM but it is not using the default configuration, you can change the URI to use a custom port or URLPrefix.
Ensure that all configurations are tested in a development environment before applying to production.
Follow the steps in the exact order to avoid configuration errors.