PowerShell Remoting for SharePoint

Well, well, well, if it isn’t our friend the double-hop authentication problem again rearing its ugly head when trying to use PowerShell remoting technologies to manage a SharePoint farm…

So you’ve run Set-WSManQuickConfig and/or Enable-PSRemoting on your server, you’ve entered an interactive shell from the client into that server, loaded the SharePoint Snapin however you will (e.g. Add-PSSnapin Microsoft.SharePoint.PowerShell), and you receive an error:

Cannot access the local farm. Verify that the local farm is properly configured, currently available, and that you have the appropriate permissions to access the database before trying again.

What’s happening is that you have presented your credentials and authenticated with the WSMan service running on the SharePoint server; the WSMan service must then authenticate *as you* to the SharePoint objects running on the server to retrieve data from the databases. And of course, by default it cannot, since it is not you and hasn’t been granted the rights to delegate your credentials.

The only working solution for this (see below on a logical solution which I haven’t yet figured out how to work) is to enable CredSSP for use when connecting to the remote PowerShell session. The Credentials Security Support Provider, or CredSSP, was created to allow users to securely send their credentials (e.g. username and password) to a service to use for authentication on their behalf to other services (Sound familiar? This is another solution for the double-hop authentication problem). Behind the scenes, CredSSP sets up a TLS session for encryption (though not for authentication) and uses SPNEGO (Kerberos or NTLM) for mutual authentication. Once mutual authentication has been achieved, the client sends the user’s credentials to the server over the encrypted TLS tunnel. With CredSSP, the client actually sends the username and password for the service’s further use (sure to make your security folks thrilled, but forewarned is forearmed).

The CredSSP authentication mechanism for WSMan (and PSRemoting) must be enabled on the server and client. In addition, the client has to be properly configured with the servers it can trust for delegation of credentials. It pays to consider again what CredSSP does – it allows the client to pass a username and password to the service for further use, so proceed cautiously.

Unforunately, in my experience the –DelegateComputer switch hasn’t worked to automatically add the trusted computers to the registry setting where they belong, so they must be set manually (using PowerShell perhaps) or via a Group Policy setting (see below).

To sum up, here are the commands to run on the server:

Enable-PSRemoting -Force Enable-WSManCredSSP -Role Server -Force

And on the client:

Enable-WSManCredSSP -Role Client -DelegateComputer * -Force Set-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\Lsa\Credssp\PolicyDefaults\AllowFreshCredentials `     -Name WSMan -Value WSMAN/* Set-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\Lsa\Credssp\PolicyDefaults\AllowFreshCredentialsDomain `     -Name WSMan -Value WSMAN/*

Note that the registry edit contained here allows delegation of credentials to any and all WSMan instances – which is not a security best practice. I’d recommend configuring the WSMAN SPNs for specific servers (e.g. WSMAN/server01.domain.local) or at least for specific domains (e.g. WSMAN/*.sub.domain.local). Alternatively, you can also use local (gpedit.msc) or domain (gpmc.msc) GPOs to configure this – the setting is at

Computer Configuration > Administrative Templates > System > Credentials Delegation > Allow Delegating Fresh Credentials.

Add SPNs (in the format WSMAN/computer.domain) to the list available in that setting. I’d recommend leaving it set to concatenate with the local server defaults.

Once the server and client have been configured properly, enter the remote session from the client, explicitly indicating the –Authentication and –Credential parameter:

Enter-PSSession server05 -Authentication CredSSP -Credential DOMAIN\username

Another unfortunate point here is that you’ll need to explicitly give a credential – you can pass a username for the –Credential parameter as shown and you’ll be prompted for your password. Alternatively, use Get-Credential and store the credential in a variable to pass for the –Credential parameter. This is a by-design limitation on the CredSSP provider.

At this point, you should be able to load the SharePoint snapin (Add-PSSnapin Microsoft.SharePoint.PowerShell) and be on your way. Note that by default PowerShell only allows members of the server’s BUILTIN\Administrators group to connect remotely. If other users need this access you will need to modify your PSSessionConfigurations (or create new ones) – but that’s a topic for another day.

One more thing before we wrap: The WSMan service creates its own SPN on the computer account for the computer on which it runs, and logically it would seem you could trust that computer account for delegation (e.g. via ADU&C) and use Kerberos authentication to connect to a remote PowerShell session on that server. The service should then be able to use Kerberos mechanisms to get and use delegated credentials. However, I haven’t been able to make this work. If you have please let me know and I’ll update this post accordingly.

Comments

• Anonymous
  March 05, 2012
  We were stuck badly on above errors. thanks for blogging this. This is very useful information.
• Anonymous
  September 04, 2012
  Any post about this:. If other users need this access you will need to modify your PSSessionConfigurations (or create new ones) – but that’s a topic for another day.thx
• Anonymous
  September 02, 2015
  I can confirm that is working with Kerberos authentication (without CredSSP): Enter-PSSession RemoteServer -Authentication Kerberos -Credential $cred We should have the SPNs for the computer account for the RemoteServer: WSMAN/RemoteServer WSMAN/RemoteServer.domain.local This should be added automaticaly. We should have the SPNs for the service account for the SQL hosting the SPS databases (FQDN:port should be enough): MSSQLSVC/SQLServer.domain.local:1433 The computer account for RemoteServer should be trusted for delegation. I tested with "Trust this computer for delegation to any service (Kerberos only)" but it should work with contraint delegation also.