Enable PowerShell Remoting with CredSSP using Group Policy

Windows PowerShell 2.0 has significantly improved the command-line experience for Windows administration, both for servers and clients. What makes it even better, though, is PowerShell Remoting, which uses Windows Remote Management (WinRM) to send commands between PowerShell sessions on different computers. WinRM is an implementation of WS-Management, an open, standardized SOAP-based web services protocol. In many ways, PowerShell Remoting is similar to SSH, although arguably less mature.

Manual Configuration

Enable PowerShell Remoting Manually

Enabling PowerShell 2.0 Remoting is simple, just run the following command from an elevated PowerShell session:

Enable-PSRemoting -Force

Once that's done, you can start using it to execute PowerShell commands from a remote host:

Invoke-Command -ComputerName $remotehost -Command { Write-Host "Hello, world!" }

Or, you can open an interactive session on the remote computer:

Enter-PSSession -ComputerName $remotehost

Enable CredSSP Manually

CredSSP is a Security Support Provider introduced with Windows Vista that enables credential delegation. In other words, it allows the remote host to access the credentials that were used to authenticate the user, and pass them on to a third host. For example, when using either basic or Kerberos authentication (the default) when connecting to a remote PowerShell session, the user would not have access to a separate file server. When using CredSSP, however, the session credentials can be passed through to the file server.

To enable CredSSP, both the client and the server must be configured to allow CredSSP. To enable CredSSP on the client side, run the following PowerShell command from an elevated session:

Enable-WSManCredSSP -Role Client -DelegateComputer $remotehost

Note: The DelegateComputer parameter specifies a list of remote hosts to which the client should be allowed to connect. It can accept wildcards, such as * for all hosts, or *.mydomain.local for any host on the mydomain.local DNS domain. If you specify a domain, however, you must always use the server's FQDN when connecting to it.

To enable CredSSP on the server side, run the following PowerShell 2.0 command from an elevated session:

Enable-WSManCredSSP -Role Server

To connect to a remote host with PowerShell Remoting using CredSSP authentication, you need to specify the Credential and Authentication parameters:

Enter-PSSession -ComputerName $remotehost -Credential (Get-Credential) -Authentication CredSSP

Note: You must specify a fully-qualified username (such as username@domain.tld or DOMAIN\username) when prompted for credentials.

The unfortunate drawback of using CredSSP is that the current implementation of the CredSSP provider for WinRM does not support delegating default credentials (i.e. the current user's credentials). Go vote for Microsoft Connect Suggestion #498377 if this bothers you; hopefully Microsoft will fix it in a future release. As such, it is best to get a PSCredential object once and store it in a variable for reuse:

$cred = Get-Credential $env:USERNAME@$env:USERDNSDOMAIN

Group Policy Configuration

Enabling PowerShell Remoting and CredSSP manually is fine for only one or two hosts, but what if it needs to be done for every machine on a network? Luckily, Group Policy is able to make all the same configuration changes the Enable-PSRemoting and Enable-WSManCredSSP cmdlets do.

There are several configuration pieces that must be set in order for everything to work correctly:

  • The Windows Remote Management service
  • Windows Firewall exceptions
  • Credential delegation
  • WinRM Client parameters
  • WinRM Service parameters

In addition, some Active Directory objects may need to have permissions changed.

It is probably best to group these settings into one or two separate GPOs, one for servers and one for clients, to keep them separate from the rest of the Group Policy settings that may already exist on the network.

Server Settings

To enable PowerShell Remoting on the server side, create a new GPO and link it an organizational unit containing the computer objects for the server machines. Open the GPO with the Group Policy editor and set the following options:

Windows Remote Management Service

  1. Navigate to Computer Configuration > Windows Settings > Security Settings > System Services
  2. Locate the Windows Remote Management (WS-Management) service and double-click it
  3. Tick the check box nexte to Define this policy setting and select Automatic. Click "OK"

Windows Firewall Exceptions

  1. Navigate to Computer Configuration > Windows Settings > Security Settings> Windows Firewall with Advanced Security > Windows Firewall with Advanced Security - LDAP://{GPO-DistinguishedName} > Inbound Rules
  2. Right-click the pane at the right and choose New Rule...
  3. Select Predefined and choose Windows Remote Management from the drop-down list. Click "Next"
  4. Remove the tick next to Windows Remote Management - Compatibility Mode (HTTP-In), but leave the one for Windows Remote Management (HTTP-In). The "Compatibility Mode" rule provides an upgrade path for systems using WinRM prior to version 2.0 and should not be enabled unless there is a specific need for it. Click "Next"
  5. Select Allow the connection and click "Finish"

WinRM Service Parameters

  1. Navigate to Computer Settings > Administrative Templates > Windows Components > Windows Remote Management (WinRM) > WinRM Service
  2. Double-click Allow automatic configuration of listeners
  3. Select Enabled
  4. In the box labeled IPv4 filter, enter a comma-separated list of IP address ranges to specify to which IP addresses the WinRM service should bind on the server. For example, 192.168.1.0-192.168.1.255 would allow the WinRM service to bind to network adapters with an IP address in that range, but no other adapter.
  5. Do the same for IPv6 filter, using IPv6 addresses instead, or leave it blank to disable WinRM over IPv6
  6. Click "OK"
  7. Double-click Allow CredSSP authentication
  8. Select Enabled
  9. Click "OK"

Client Settings

To enable PowerShell remoting on the client side, create a new GPO and link it to an organizational unit containing the computer objects for the client machines. Open the GPO with the Group Policy editor and set the following options:

Credential Delegation

  1. Navigate to Computer Settings > Administrative Templates > System > Credentials Delegation
  2. Double-click Allow Delegating Fresh Credentials
  3. Select Enabled
  4. Click "Show..."
  5. Enter a list of service principal names representing hosts to which clients should be allowed to delegate credentials. Wildcards are allowed in the host name portion of the SPN. For example:
    • WSMAN/Server01 — Allows delegation only to the server named Server01, and only using its single-label name
    • WSMAN/Server01.mydomain.local — Allows delegation only to the server named Server01, and only using its fully-qualified domain name
    • WSMAN/*.mydomain.local — Allows delegation to any host on the mydomain.local DNS domain, using their fully-qualified domain names only
    • WSMAN/* — Allows delegation to any host by any name
  6. Click "OK"
  7. Click "OK"

WinRM Client Parameters

  1. Navigate to Computer Settings > Administrative Templates > Windows Components > Windows Remote Management (WinRM) > WinRM Client
  2. Double-click Allow CredSSP authentication
  3. Select Enabled
  4. Click "OK"
  5. Double-click Trusted Hosts
  6. Select Enabled
  7. In the box labeled TrustedHostList, enter a comma-separated list of hosts the client should trust. Wildcards are allowed, and there is a special <local> value meaning trust all single-label names. For example:
    • Server01 — Trust only the server named Server01, and only using its single-label name
    • server01.mydomain.local — Trust only the server named Server01, and only using its fully-qualified domain name
    • *.mydomain.local — Trust any host on the mydomain.local DNS domain, using their fully-qualified domain names only
    • <local> — Trust any host by single-label name
    • * — Trust any host by any name
  8. Click "OK"

Troubleshooting

Here are some common error messages and some troubleshooting tips for each:

Operation timed out

Enter-PSSession : Connecting to remote server failed with the following error me
ssage : The WinRM client cannot complete the operation within the time specified
. Check if the machine name is valid and is reachable over the network and firew
all exception for Windows Remote Management service is enabled. For more informa
tion, see the about_Remote_Troubleshooting Help topic.
  • Can you ping the machine using the same name you used for the ComputerName parameter?
  • If the settings are defined in Group Policy, has the machine performed a policy refresh? Force one by running gpupdate /target:computer with elevated privileges
  • Does the machine have the Windows Remote Management (HTTP-In) rules enabled in Windows Firewall?
  • Is the Windows Remote Management (WS-Management) service running on the machine?

Policy does not allow delegation of user credentials

Enter-PSSession : Connecting to remote server failed with the following error me
ssage : The WinRM client cannot process the request. A computer policy does not 
allow the delegation of the user credentials to the target computer. Use gpedit.
msc and look at the following policy: Computer Configuration -> Administrative T
emplates -> System -> Credentials Delegation -> Allow Delegating Fresh Credentia
ls.  Verify that it is enabled and configured with an SPN appropriate for the ta
rget computer. For example, for a target computer name "myserver.domain.com", th
e SPN can be one of the following: WSMAN/myserver.domain.com or WSMAN/*.domain.c
om. For more information, see the about_Remote_Troubleshooting Help topic.
  • Make sure the name specified in the ComputerName parameter matches the SPN specified in the GPO. If the policy specifies a wildcard with a domain name, for example, make sure the ComputerName parameter is the fully-qualified domain name of the remote host, not just its single-label name

The target computer is not trusted

Enter-PSSession : Connecting to remote server failed with the following error me
ssage : The WinRM client cannot process the request. A computer policy does not 
allow the delegation of the user credentials to the target computer because the 
computer is not trusted. The identity of the target computer can be verified if 
you configure the WSMAN service to use a valid certificate using the following co
mmand: winrm set winrm/config/service '@{CertificateThumbprint="<thumbprint>"}' 
 Or you can check the Event Viewer for an event that specifies that the followin
g SPN could not be created: WSMAN/<computerfqdn>. If you find this event, you ca
n manually create the SPN using setspn.exe .  If the SPN exists, but CredSSP can
not use Kerberos to validate the identity of the target computer and you still w
ant to allow the delegation of the user credentials to the target computer, use 
gpedit.msc and look at the following policy: Computer Configuration -> Administr
ative Templates -> System -> Credentials Delegation -> Allow Fresh Credentials w
ith NTLM-only Server Authentication.  Verify that it is enabled and configured w
ith an SPN appropriate for the target computer. For example, for a target comput
er name "myserver.domain.com", the SPN can be one of the following: WSMAN/myserv
er.domain.com or WSMAN/*.domain.com. Try the request again after these changes. 
For more information, see the about_Remote_Troubleshooting Help topic.
  • Make sure the remote host has a Service Principal Name starting with WSMAN and matching the value specified in the ComputerName parameter. To list a host's service principal names, run setspn -l <computername> with elevated privileges on a domain controller. If a proper SPN does not exist, try restarting the Windows Remote Management (WS-Management) service, and check the System event log for event ID 10154. If that event exists, you will need to modify permissions in Active Directory in order for hosts to be able to register their SPNs correctly (see below)
  • Make sure you are specifying a fully-qualified user name in the PSCredential object passed to the Credential parameter (i.e. DOMAIN\username or username@domain.local)

Modifying Active Directory Permissions

Note: Perform these steps ONLY if you receive the "target computer is not trusted" error, Windows Remote Managment logs event ID 10154 in the System event log, and setspn -l does not list any WSMAN/... SPNs for the remote host!

  1. Open ADSI Edit
  2. Click Action > Connect to...
  3. Under Connection Point, select Select a well known Naming Context and choose Default naming context
  4. Under Computer, select Default (Domain or server that you logged in to)
  5. If your domain controllers support it (i.e. you are running Active Directory Certificate Services), tick Use SSL-based Encryption
  6. Expand the objects in the tree at the left until you find the container containing the computer object for the server exhibiting the issue, such as CN=Computers
  7. Right-click on the container object and choose Properties
  8. Click the Security tab
  9. Click "Advanced"
  10. Click "Add..."
  11. In the box labeled Enter the name of the object to select, enter NETWORK SERVICE
  12. In the drop-down list labeled Apply to, select Descendant Computer objects
  13. Scroll all the way to the bottom of the Permissions list and tick the box in the Allow column for Validated write to service principal name
  14. Tick Apply these permissions to objects and/or containers within this container only
  15. Click "OK"
  16. Click "OK"
  17. Click "OK"
  18. Repeat steps 6-17 for any container with computer objects for hosts on which PowerShell Remoting is enabled
  19. Restart the Windows Remote Management (WS-Management) service on the affected hosts
  20. Run setspn -l <computername> with elevated privileges on a domain controller to verify that the SPN was correctly created