SharePoint Server で PowerShell を使用する際の準備事項

こんにちはSharePoint サポートの森　健吾 (kenmori) です。
今回の投稿では、PowerShell を使用し、タスクスケジューラーや運用管理ソフトなどでバッチ実行するといったシナリオにおいて必要になる情報をまとめてみました。

1. PowerShell 実行ユーザーに必要な権限

PowerShell の実行アカウントとして必要な権限は、以前弊社サポート ブログにも記載されたコンソール アプリケーションで SharePoint オブジェクト モデルを実行する場合と同じです。
アプリケーション プールに代わって powershell.exe がプロセス ホストとなりますため、実行アカウントはアプリケーション プール同等の権限を必要とします。

タイトル : コンソールアプリケーションを実行する際の権限について
アドレス: https://blogs.technet.com/b/sharepoint_support/archive/2011/11/17/3465737.aspx

システム アカウントなどといった強い権限を使用して定期的にジョブを実行することをご検討いただいている場合は、本項 (1. ) の内容を検討する必要はございません。

ジョブ実行用のアカウントを別途作成して構築する場合は、Add-SPShellAdmin を実行してアカウントに権限を付与し、さらに足りない権限を補うように手動で設定することがお勧めです。
Add-SPShellAdmin では指定されたアカウントに対し、簡単にある程度必要な権限をまとめて付与することができます。

タイトル : Add-SPShellAdmin
アドレス : https://technet.microsoft.com/ja-jp/library/ff607596(v=office.14).aspx

SharePoint Server 上でコマンドを実行するにあたり最低限必要となる基盤側の主なリソースとしてファイル、レジストリ、構成データベース、コンテンツ データベースなどがありますが、Add-SPCmdShellAdmin を実行すると、-UserName オプションに指定されたアカウントは以下のようなグループやロールに所属します。

(※1) SharePoint が内部的に参照する様々なファイルやレジストリには、WSS_ADMIN_WPG (ローカル セキュリティグループ) に対するアクセス権が付与されています。
(※2) 構成データベースが持つデータベース ロール SharePoint_Shell_Access ロールはdb_owner に所属します。 db_owner は SharePoint が内部的に実行するデータベース操作に必要な権限を保持しています。
(※3) コンテンツ DB に対しては、Add-SPShellAdmin の –database オプションを使用して権限付与することが必要となります。
   コンテンツ DB の GUID については Get-SPContentDatabase コマンドを実行して列挙し、該当のコンテンツ DB の Id を探してください。

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

タイトル : Get-SPContentDatabase
アドレス : https://technet.microsoft.com/ja-jp/library/ff607828(v=office.14).aspx

なお、テスト環境などでセキュリティを気にしないのであれば、sysadmin サーバー ロールに加えてしまうのも手段としてはあります。

タイトル : データベース レベルのロール
アドレス : https://technet.microsoft.com/ja-jp/library/ms189121.aspx

タイトル : サーバー レベルのロール
アドレス : https://technet.microsoft.com/ja-jp/library/ms188659.aspx

さらに、実行するコマンドの内容によっては、コードが参照するクラスやメソッドなどにもとづき、以下のような権限が必要となることもありますのでご注意ください。

・SharePoint サイト コンテンツ (サイト、リスト、アイテム等へのアクセス権)
・サーバーの BUILTIN\Administrators 権限 (一部の管理タスクを実行する場合など)

注意点

運用管理ソフトを使用していて、この製品が常駐プロセスに使用する実行アカウントを PowerShell 用のユーザーとして登録する場合、Add-SPShellAdmin などを実行後に常駐プロセスまたはサーバーを再起動することを忘れないようにしてください。

プロセス起動時にはプライマリ トークンが生成され、プロセスは以後それをキャッシュし続けます。このトークンには、実行アカウント情報のみならず、トークン生成時にアカウントが所属するセキュリティ
グループの一覧や特権等を保持しています。
そのため、特に常駐する運用管理ソフトなどがプロセスを起動した後に権限変更した場合、そのプロセスが新しいプロセスを起動する (子プロセスを作成する) と、権限変更が反映されていない過去のトークンを継承して起動する動作となります。
つまり、WSS_ADMIN_WPG や BUILTIN\Administrators などに新しく加わったことを反映するためには、設定変更後の常駐プロセスの再起動が必要となります。

なお、製品によっては、このような常駐プロセスから PowerShell を起動したり、現在のログオン セッションからトークン情報を取得し、複雑な偽装を実施したりするものがございます。そのため、今回のような手順で構築する際に、権限変更を確実に反映するためには、すべてのトークンをリフレッシュするようはじめからサーバーの再起動を計画しておくことが安全です。

2. PowerShell コマンドレットの実行ファイル (*.ps1)

SharePoint 用 PowerShell スナップインの追加

SharePoint 用のコマンドレットを使用するためには、以下の一行を挿入します。

Add-PSSnapin Microsoft.SharePoint.PowerShell

*.ps1 で PowerShell を実行すると、Windows PowerShell が起動してコマンドを実行する動作となります。SharePoint 管理シェルは標準で SharePoint 用のコマンドレットをロードしていますので、同じようなコマンドを使用する場合には、PowerShell スクリプト ファイル側で明示的にスナップインをロードさせる必要があります。

(例)
Add-PSSnapin Microsoft.SharePoint.PowerShell
[Microsoft.SharePoint.SPSecurity]::RunWithElevatedPrivileges(
{
  $web = Get-SPWeb https://sharepoint/sites/site/subA/
  Write-Host $web.Title
  foreach ($user in $web.SiteUsers) {
    Write-Host $user.Name
  }
})

PowerShell 実行ポリシーの変更

PowerShell スクリプト (*.ps1) を実行する場合は、実行ポリシーを既定の Restricted から最低限 RemoteSigned に指定することも忘れずに実施しましょう。

タイトル: Set-ExecutionPolicy コマンドレットの使用
アドレス: https://technet.microsoft.com/ja-jp/library/ee176961.aspx

3. PowerShell リモート実行に必要な設定

PowerShell をリモートから実行したいというご要望もよくあるお問い合わせです。これを実現するためには、Windows PowerShell リモート処理を実施します。
方法は色々考えられますが、一番簡単な方法は Invoke-Command の実行です。

タイトル : Invoke-Command
アドレス : https://technet.microsoft.com/ja-JP/library/dd347578.aspx

このコマンドを呼び出すまでに必要な準備を以下に記載します。

準備 1) Enable-PSRemoting

Invoke-Command を実行するためには、あらかじめリモート処理の対象となるサーバーにおいて Enable-PSRemoting を実行して置く必要があります。

Enable-PSRemoting は、WinRM サービスの起動と構成、要求を受信するためにリスナー生成、WS-Management 通信のためのファイヤーウォール除外の登録、その他さまざまな構成をまとめて実施します。

タイトル : Enable-PSRemoting
アドレス : https://technet.microsoft.com/en-us/library/hh849694.aspx

準備 2) 資格情報委任の設定

認証情報を指定する場合は、資格情報の委任を許可する設定を WinRM クライアント側 (PowerShell コマンドを実行するクライアント側) で実施しておく必要があります。
以下の 2-1 または 2-2 の手順のいずれかを実行ください。

2-1) PowerShell で設定しておく場合

PowerShell を管理者で起動した上で、以下のコマンドを実行します。

Enable-WSManCredSSP -Role Client -DelegateComputer sharepointwfe1

2-2) 手動で設定しておく場合

1. ファイル名を指定して実行から gpedit.msc を起動します。
2. [コンピューターの構成] -> [管理用テンプレート] -> [システム] -> [資格情報の委任] -> [新しい資格情報の委任を許可する] を開きます。

3. ポリシーを有効にします。
4. [表示] をクリックします。

5. 対象のサーバー (WSMAN/servername) を登録します。

さて、準備はできましたので、あとはクライアント環境から Invoke-Command を含む以下のようなコマンドを実行してみましょう。

(例)
$user = "domain\psuser1 "
$passtr = "password"
$password = ConvertTo-SecureString $passtr -AsPlainText -Force
$psc = New-Object System.Management.Automation.PsCredential($user, $password)
$cred = Get-Credential -Credential $psc
$sess = New-PSSession -ComputerName sharepointwfe1 -Authentication CredSSP -Credential $cred

Invoke-Command -Session $sess -ScriptBlock {
  Add-PSSnapin Microsoft.SharePoint.PowerShell
  [Microsoft.SharePoint.SPSecurity]::RunWithElevatedPrivileges( {
    $web = Get-SPWeb https://sharepoint/sites/siteA/
    Write-Host $web.Title
    foreach ($user in $web.SiteUsers) {
      Write-Host $user.Name
    }
  })
}

以下の記事も併せてご参考にしてください。

タイトル : Windows PowerShell: リモート処理について
アドレス : https://technet.microsoft.com/ja-jp/magazine/gg981683.aspx

また、以下に PowerShell を使用した SharePoint の管理に関する役立つ情報をご紹介します。併せてご参考にしてください。

タイトル : Windows PowerShell を使用した SharePoint 2010 製品の管理
アドレス : https://technet.microsoft.com/ja-jp/library/ee806878(v=office.14).aspx

タイトル: Windows Powershell を使用して SharePoint 2013 を管理する
アドレス : https://technet.microsoft.com/ja-jp/library/ee806878.aspx

いかがでしたでしょうか。今回の投稿は以上になります。