Configure SharePoint Servers from your Win7 or Server 2008 R2 Desktop with PowerShell Remoting

See Technet or Don Jones Technet Mag or Zach Rosenfield or Jei Li or Ravikanth Chaganti

There are many steps to get this working, you have to conquer the double hop scenario. Basically, to enable remoting, you run winrm quickconfig, change group policies, run Enable-PSRemoting command, run SharePoint_Shell_Access powershell command and then authenticate with CredSSP.

Note: You need to run all cmdlets in an elevated prompt.

Quick Start

Once you set your machines up per this article and understand the process, here are the only steps you need to do on client and servers.

Server

Enable-PSRemoting
Enable-WSmanCredSSP -Role server
Set-Item WSMan:\localhost\Shell\MaxMemoryPerShellMB 1000

Client

Enable-PSRemoting
Enable-WSManCredSSP -Role Client -DelegateComputer "sp7"

# To test communication without SharePoint
Invoke-Command -ComputerName sp7.nwi.local -Credential NWI\SPFarmAdmin -Authentication CredSSP -Script {HostName}

# Enter a session using CredSSP Protocol
Enter-PSSession –ComputerName sp7 -Authentication CredSSP –Credential NWI\SPFarmAdmin

#To talk to SharePoint
$ver = $host | select version
if ($ver.Version.Major -gt 1) {$Host.Runspace.ThreadOptions = "ReuseThread"}
Add-PsSnapin Microsoft.SharePoint.PowerShell
Set-location $home

Add-PSSnapin Microsoft.SharePoint.Powershell

 

Lets talk about Security around SharePoint and PowerShell

To be allowed to execute PowerShell commands against a specific site collection, the user running the script needs certain access to both the database and every web front end in the farm.

There are only two requirements for most commands. The user must be:

  1. A member of the WSS_ADMIN_WGP group (this is a Windows Group on the machine the user is executing commands on)
  2. A member of the “SharePoint_Shell_Access” role on the SharePoint databases (this is a SQL Role)
    To simplify the management of these roles Microsoft has created a set of PowerShell commands (noun is “SPShellAdmin”) to add and remove SharePoint permissions and allow you to designate a specific database, this is because the “Shell Admin” role by default only gives the user access to the Configuration Database; the shell admin must be given access to each individual service and content database they are “allowed to manipulate”
    To run SPShellAdmin command, user should be the install account used to setup the farm because the user executing the command must have Securityadmin server role access on the SQL instance and the db_owner role on the database you assign rights to. Also the user must be local administrator in the local computer.

Syntax calling the command:

Add-SPShellAdmin [-UserName] <String>
[-AssignmentCollection <SPAssignmentCollection>]
[-Confirm [<SwitchParameter>]]
[-database <SPDatabasePipeBind>]
[-WhatIf [<SwitchParameter>]] [<CommonParameters>]

Examples:

This example adds a new user named User1 to the SharePoint_Shell_Access role in the farm configuration database only, and also ensures the user is added to the WSS_Admin_WPG local group on each server in the farm.

Add-SPShellAdmin -UserName CONTOSO\User1

This example adds a new user named User1 to the SharePoint_Shell_Access role in both the specified content database and the configuration database, and also ensures the user is added to the WSS_Admin_WPG local group on each farm server.

$contentDB = Get-SPDatabase | ?{$_.Name -eq "wss_content"}
Add-SPShellAdmin -UserName CONTOSO\User1 -database $contentDB

This example adds a new user named User1 to the SharePoint_Shell_Access role in both the specified content database and the configuration database by passing a database GUID to the cmdlet.

Add-SPShellAdmin -UserName CONTOSO\User1 -database 4251d855-3c15-4501-8dd1-98f960359fa6

This example adds a new user named User1 to the SharePoint_Shell_Access role in both the specified Central Administration content database and the configuration database.

Get-SPDatabase | Where-Object {$_.WebApplication -like "SPAdministrationWebApplication"} | Add-SPShellAdmin CONTOSO\User1

How to handle the double hop scenario

PowerShell 2.0 remoting is built on top of WinRM so we can use CredSSP to perform multi-hop authentication. Credential Security Service Provider (CredSSP) is a new security service provider that enables an application to delegate the user’s credentials from the client to the target server, then to the SQL Server. Command will fails without CredSSP because the remote session tries to access Server using the machine credentials instead of the credentials used to invoke the remote session. We could have successfully accessed the server if there was a way to pass or delegate credentials from the client so that we can authenticate to the Server. This is what is called multi-hop authentication and PowerShell remoting enables this using CredSSP.

Enable Credential Security Service Provider (CredSSP)

We need to enable CredSSP authentication, once again because any command that talks to SharePoint cmdlets that itself talks to SQL (which is most commands) will need to call SQL “as you”. This means you need the ability to “double hop”—which CredSSP provides. This is enabled using the “Enable-WSmanCredSSP” cmdlets.

Enable-WSManCredSSP -Role Client -DelegateComputer "*.sp.local"

Of course this will still not work, you have to do this on Windows 7

Use gpedit.msc and look at the following policy: Computer Configuration -> Administrative Templates -> System -> Credentials Delegation -> Allow Delegating Fresh Credentials.  Verify that it is enabled and configured with an SPN appropriate for the target computer. For example, for a target computer name "myserver.domain.com", the SPN can be one of the following: WSMAN/myserver.domain.com or WSMAN/*.domain.com. For more information, see the about_Remote_Troubleshooting Help topic.

This will enable all clients in the domain. As shown here, you can use Enable-WSManCredSSP cmdlet to enable CredSSP authentication and specify the computer role as client. When the computer role is defined as a client, you can also specify the DelegateComputer parameter to specify the server or servers that receive the delegated credentials from the client. The delegateComputer accepts wildcards as shown above. You can also specify “*” to specify all computers in the network.

This will enable CredSSP on  the sever

Enable-WSManCredSSP -Role Server

Now when we invoke commands etc, we specify the authentication method as CredSSP and pass the credentials as per the following example. See the parameter –Authentication to specify the authentication method as CredSSP

Invoke-Command -ComputerName sp7 -Credential NSA\NSAFarmAdmin -Authentication CredSSP -Script {HostName}

Create and enter a remote sessions to SharePoint Servers from Client

If your current user on client machine has permission to the SharePoint farm and Windows PowerShell on the remote box, you can use Enter-PSSession to create and enter the remote session. If it works, the command prompt will be changed to [SP7.nsa.local]: PS C:\Users\Administrator\>.

Enter-PSSession –ComputerName sp7.nsa.local

The session will be closed when you type exit or Exit-PSSession. You can also use New-PSSession to create the session to use with Invoke-Command.

To connect to a machine with CredSSP and a different credential, you can use

Enter-PSSession –ComputerName sp7.nsa.local -Authentication CredSSP –Credential nsa\nsafarmadmin

This will pop up a dialogue for you to type in password. If you want this process to be fully automated, you can store the credential first into a file.

Load SharePoint Windows PowerShell Snap-in

Unlike SharePoint Management Shell, You need to load this snap-in manually to use the cmdlets for SharePoint.

Add-PSSnapin Microsoft.SharePoint.Powershell 

 

Store and use credentials for scripting

A credential in Windows PowerShell is a object which contains username (as plain text) and password (as secure string).  First, use the following command to covert password from keyboard input to a secure string in a text file.

Read-Host -AsSecureString | ConvertFrom-SecureString | out-file C:\crd-sharepoint.txt

When you need to create a credential object, read this password (the secure string) from the file and create the credential with the following command:

$pwd = Get-Content C:\crd-sharepoint.txt | ConvertTo-SecureString

then create the credential (replace myusername with your domain\username):

$crd = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList "myusername",$pwd

 

Then you will be able to use this credential in the command line without any dialogue.

Enter-PSSession -ComputerName sharepoint.contoso.com -Authentication CredSSP -Credential $crd

Load SharePoint Windows PowerShell Snap-in

Unlike SharePoint Management Shell, You need to load this snap-in manually to use the cmdlets for SharePoint.

 

Summary

Run this on SharePoint Server to allow PoweShell Admin Access to Farm and Content databases.

Add-SPShellAdmin -UserName nsa\nsafarmadmin-database MyContentDatabase

Run this on the server to enable remoting and increase memory

Enable-PSRemoting

Enable-WSmanCredSSP -Role server

Set-Item WSMan:\localhost\Shell\MaxMemoryPerShellMB 1000

Plus you may need to run winrm quickconfig to allow remote access to a server per this graphic.

image

Now run this on the Client

Enable-PSRemoting

Enable-WSManCredSSP -Role Client -DelegateComputer "*.sp.local"

Connect to a machine with CredSSP, In your cmdlet make sure you specify  -Authentication CredSSP  -Credential nsa\nsaFarmAdmin

Enter-PSSession –ComputerName sp7.nsa.local -Authentication CredSSP –Credential nsa\nsafarmadmin

Add the SharePoint Snap in

Add-PSSnapin Microsoft.SharePoint.Powershell

 

You can use Disable-WSManCredSSP to disable CredSSP authentication on a client or a server computer.

Disable-WSManCredSSP -Role Client            

Disable-WSManCredSSP -Role Server

You can use Get-WSManCredSSP cmdlet to verify if a computer has CredSSP enabled and also the role (client/server).

 

Advertisements