次の方法で共有

SharePoint の信頼度の高い構成スクリプト

  • [アーティクル]

以下のスクリプトは、Microsoft SharePoint のステージング ファームまたは運用ファームのアクセス トークンの信頼できる発行元として、1 つ以上の X.509 デジタル証明書を指定する場合に使用されます。 SharePoint アドイン開発環境にさらに適したスクリプトについては、「SharePoint の高信頼性アドインを作成する」を参照してください。証明書の取得と保存には非常に多くの方法があるため、どの SharePoint ファームでも機能する単一のスクリプト セットは存在しません。 このため、以下の点に注意してください。

  • スクリプトとは、ファーム内の任意の SharePoint サーバー上にあり、SharePoint 管理シェルで実行するものです。

  • これらのスクリプトは、カスタマイズが必要な下書きと考えるべきものです。

  • これらは高信頼 SharePoint アドインを発行するプロセス全体の一部として使用されます。 トピック「高信頼認証を使用する SharePoint アドインを作成する」、「高信頼 SharePoint アドインをパッケージ化して発行する」、およびこれらに記載されている前提条件を理解しているユーザーのみが使用してください。

  • アドインの顧客の証明書ポリシーを理解しているユーザーが、必要に応じて確認とカスタマイズを行います。

  • 後述する HighTrustConfig-ForSharedCertificate.ps1 と HighTrustConfig-ForSingleApp.ps1 の 2 つの主要なスクリプトは、管理者がアドインのリモート Web アプリケーション コンポーネントの証明書を取得しており、SharePoint サーバー上の次の IIS アプリケーション プールのユーザー アカウントが読み取り権限を持つフォルダーに、管理者が (秘密キーを含まない) .cer バージョンの証明書を一時的に保存していることを想定しています。

    • SecurityTokenServiceApplicationPool

    • テスト用 SharePoint Web サイトの親 SharePoint Web アプリケーションをホストする IIS Web サイトに対応するアドイン プールです。 SharePoint - 80 IIS Web サイトに対応するプールは OServerPortalAppPool という名前になります。

      アプリケーション プールが使用しているユーザー アカウントを検索するには、SharePoint サーバーで IIS マネージャーを開き、 [ 接続] ペインの [ アプリケーション プール] をダブルクリックします。 [アプリケーション プール] リストの [ID] 列が開き、アプリケーション プールのユーザーが表示されます。

  • また、2 つの主要なスクリプトの手順は、リモート Web アプリケーションをホストするサーバーの IIS に証明書がインストールされていることも想定しています。 手順については、「証明書によるリモート Web サーバーの構成」を参照してください。

以下のセクションでは、各スクリプト固有の使用上の注意を参照してください。

AddSPRootAuthority.ps1

高信頼 SharePoint アドインのリモート Web アプリケーション コンポーネントの証明書は、商用の証明機関 (CA) またはドメインの CA のいずれかから取得します。 どちらの場合でも、この証明書はルート CA (商用またはドメイン) を起点として、それぞれがその上位を信頼する証明書チェーンの最も低いリンクになります。 SharePoint では、チェーンのすべての証明書が、SharePoint の信頼されたルート証明機関のリストに追加されている必要があります。

以下のスクリプトは、最も低いものを除き、チェーンの各証明書をリストに追加するために使用できます。 チェーンの最も低い証明書はリモート Web アプリケーションに直接バインドされる証明書ですが、後のセクションで説明する主要なスクリプトの 1 つにより、ルート証明機関に追加されます。

スクリプトのパラメーターは次のとおりです。

パラメーター 値
-CertPath 証明書の完全なパスとファイル名 (.cer ファイル)。
-CertName 証明書の名前。 名前を見つけるには、証明書のプロパティを表示します。

たとえば、Web アプリケーションの証明書が中間 (別名エンタープライズ) CA サーバーによって発行され、証明書が、ルート (別名スタンドアロン) CA サーバーによって発行される一般的なシナリオでは、スクリプトは、2 つの CA サーバーの証明書ごとに 1 回ずつ実行する必要があります。 このことを以下に示します。

./AddSPRootAuthority.ps1 -CertPath "\\CertStorage\RootCA.cer" -CertName "Contoso Root CA"

./AddSPRootAuthority.ps1 -CertPath "C:\RegionalCerts\NorthRegion.cer" -CertName "North Region Intermediate CA"

顧客の高信頼 SharePoint アドインのすべての証明書が同じ証明書チェーンからのものである標準的なケースの場合、このスクリプトをもう一度使用することはありません。

スクリプトのコードは以下のとおりです。 テキスト エディターや PowerShell エディター (IPowerShell ISE) に貼り付けて、AddSPRootAuthority.ps1 として保存します。

注:

ファイルは UTF-8 形式ではなく ANSI 形式で保存する必要があります。 PowerShell で ANSI 以外の形式のファイルを実行すると、構文エラーが発生する場合があります。 メモ帳および PowerShell エディターでは、既定で ANSI 形式で保存されます。 その他のエディターを使用してファイルを保存するときは、必ず ANSI 形式で保存してください。

param(
  [Parameter(Mandatory)][String] $CertName = $(throw "Usage: AddSPRootAuthority.ps1 -CertPath <full path to .cer file> -CertName <name of certificate>"),
  [Parameter(Mandatory)][String] $CertPath
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Make the certificate a trusted root authority in SharePoint
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
New-SPTrustedRootAuthority -Name $CertName -Certificate $cert

HighTrustConfig-ForSharedCertificate.ps1

このスクリプトの主なタスクは、複数の高信頼 SharePoint アドインのリモート Web アプリケーション コンポーネントの共有証明書を、ルート証明機関および信頼されたアクセス トークン発行元の両方として SharePoint に登録することです。 このスクリプトは、顧客がそれぞれの高信頼 SharePoint アドインと共に個別の証明書を使用している場合は使用されません。 そのシナリオについては、「 HighTrustConfig-ForSingleApp.ps1」を参照してください。 すべてのアドインが同じ証明書を使用している場合、このスクリプトは 1 回だけ実行します。 アドインの一部のセットが他のセットとは異なる証明書を使用している場合、このスクリプトはセットごとに 1 回実行します。

次の表に、スクリプトのパラメーターとスイッチについて説明します。 スクリプトをカスタマイズする場合に、この表への変更が必要になることがあります。

パラメーター 値
-CertPath (必須) 共有される *.cer ファイルの完全なパス。
-CertName (必須) 共有される証明書の名前。 名前を検索するには、リモート Web アプリケーションをホストするリモート Web サーバーの IIS を開きます。 [サーバー名] ノードを強調表示して、[証明書] をダブルクリックします。 証明書が名前順で一覧表示されます。
-TokenIssuerFriendlyName
(省略可能)		 トークン発行元の、最長 50 文字の一意でわかりやすい名前。 これは、トークン発行元に関連した問題をデバッグする際に役立ちます。

名前は一意である必要があります。 GUID を含めれば一意性は保証されますが、GUID が 50 文字のうちの 32 文字までを使用するので、GUID を Base 64 文字列に変換することを考慮してください。そうすれば、22 文字にまで減らせます。

このパラメーターを使用しない場合、スクリプトは High-Trust Add-ins <base64 version of issuer GUID> という名前を使用します。

このスクリプトの実行例を次に示します。

./HighTrustConfig-ForSharedCertificate.ps1 -CertPath "C:\Certs\MyCert.cer" -CertName "My Cert" -TokenIssuerFriendlyName "SharePoint High-Trust Add-ins Token Issuer"

重要

トークン発行元としての証明書の登録は、即座には有効になりません。 すべての SharePoint サーバーで新しいトークン発行元が認識されるまで、最大 24 時間かかる場合があります。 すべての SharePoint サーバーで iisreset を実行すると、SharePoint ユーザーを邪魔することなく発行者をすぐに認識できるようになります。

テキスト エディターか PowerShell エディターで新しいファイルを作成して、テキスト ファイルに以下をコピーし、HighTrustConfig-ForSharedCertificate.ps1 として保存します。 UTF-8 形式ではなく、ANSI 形式を使用します。

param(
  [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSharedCertificate.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-TokenIssuerFriendlyName <friendly name>]"),
  [Parameter(Mandatory)][String] $CertName,
  [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
  throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}

# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)

# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate

# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm

# Generate a unique specific issuer ID
$specificIssuerId = [System.Guid]::NewGuid().ToString()

# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
  $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
  $tokenIssuerName = "High-Trust Add-ins " + [System.Convert]::ToBase64String($specificIssuerId.ToByteArray()).TrimEnd('=')
}

# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker

# Output the specific issuer ID to a file in the same folder as this script. The file should be given to the developer of the high-trust SharePoint Add-in.
$specificIssuerId  | Out-File -FilePath "SecureTokenIssuerID.txt"

ヒント

New-SPTrustedRootAuthority 行が正常に実行された後にスクリプトがエラーをスローした場合、そのオブジェクトが削除されるまで、スクリプトを再実行することはできません。 -Identity パラメーターの値が、スクリプトの -CertName パラメーターで使用されたものと同じ場合は、次のコマンドレットを使用します: Remove-SPTrustedRootAuthority -Identity <certificate name>

トークン発行元を何らかの理由で削除する必要がある場合は、次のコマンドレットを使用します: Remove-SPTrustedSecurityTokenIssuer -Identity <issuer name>

-TokenIssuerFriendlyName パラメーターが使用されていた場合は、-Identity と同じ値を使用します。

-TokenIssuerFriendlyName パラメーターが使用されていなかった場合は、発行元名の一部はランダムな GUID になります。 -Identity に必要な値を取得するには、次のコマンドレットを実行します。 生成される TokenIssuers.txt ファイルを開き、High-Trust Add-ins <base64 version of issuer GUID> という名前の発行元を検索します。 -Identity の名前全体を使用します。

Get-SPTrustedSecurityTokenIssuer | Out-File -FilePath "TokenIssuers.txt"

HighTrustConfig-ForSingleApp.ps1

このスクリプトの主なタスクは、高信頼 SharePoint アドインのリモート Web アプリケーションの証明書を、ルート証明機関および信頼されたアクセス トークン発行元の両方として SharePoint に登録することです。 このスクリプトは、顧客が複数の SharePoint アドインに単一の証明書を使用しているときは使用されません。そのような場合については、「HighTrustConfig-ForSharedCertificate.ps1」を参照してください。 このスクリプトは、それぞれの高信頼 SharePoint アドインで実行されます。

次の表に、スクリプトのパラメーターとスイッチについて説明します。 スクリプトをカスタマイズする場合に、この表への変更が必要になることがあります。

パラメーター 値
-CertPath (必須) 共有される *.cer ファイルの完全なパス。
-CertName (必須) 共有される証明書の名前。 名前を検索するには、リモート Web アプリケーションをホストするリモート Web サーバーの IIS を開きます。 [サーバー名] ノードを強調表示して、[証明書] をダブルクリックします。 証明書が名前順で一覧表示されます。
-SPAppClientID (必須) SharePoint アドインを appregnew.aspx に登録したときに使用したクライアント ID (GUID)。
これは、トークン発行元の発行元 ID として使用されます。 スクリプトは、発行元 ID の要件である小文字が使用されていることを確認します。
-TokenIssuerFriendlyName
(省略可能)		 トークン発行元の、最長 50 文字の一意でわかりやすい名前。 これは、トークン発行元に関連した問題をデバッグする際に役立ちます。
名前は一意である必要があります。 SharePoint アドインの名前を使用することをご検討ください。 このパラメーターを使用しない場合、スクリプトは -SPAppClientID の値を名前として使用します。

スクリプトの呼び出しの例を次に示します。

./HighTrustConfig-ForSingleApp.ps1 -CertPath "\\MyServer\Certs\MyCert.cer" -CertName "My Cert" -SPAppClientID "afe332f4-1f87-4c31-89b8-9c343ad7f24e" -TokenIssuerFriendlyName "Payroll add-in"

重要

トークン発行元としての証明書の登録は、即座には有効になりません。 すべての SharePoint サーバーが新しいトークン発行者を認識するまでに、24 時間程かかることがあります。 SharePoint ユーザーに影響を与えずに実行できる場合は、すべての SharePoint サーバーで iisreset を実行すると、発行者がすぐに認識されます。

テキスト エディターか PowerShell エディターで新しいファイルを作成して、テキスト ファイルに以下をコピーし、HighTrustConfig-ForSingleApp.ps1 として保存します。 UTF-8 形式ではなく、ANSI 形式を使用します。

param(
  [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSingleApp.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-SPAppClientID <client ID of SharePoint add-in>] [-TokenIssuerFriendlyName <friendly name>]"),
  [Parameter(Mandatory)][String] $CertName,
  [Parameter(Mandatory)][String] $SPAppClientID,
  [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"

# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
  throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}

# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)

# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate

# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm

# Must use the client ID as the specific issuer ID. Must be lower-case!
$specificIssuerId = New-Object System.String($SPAppClientID).ToLower()

# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm

# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
  $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
  $tokenIssuerName = $specificIssuerId
}

# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier

ヒント

前のセクションの最後にあるヒントがここにも適用されます。ただし、HighTrustConfig-ForSingleApp.ps1 で -TokenIssuerFriendlyName パラメーターが使用されていなかった場合は、Remove-SPTrustedSecurityTokenIssuer コマンドレットの -Identity パラメーターでクライアント ID を使用してください。

サイト サブスクリプションに必要な変更

サイト サブスクリプションはテナンシーと呼ばれることもありますが、SharePoint ファームのサイト コレクションのサブセットです。 通常は、サイト サブスクリプションは、ホストされている SharePoint ファーム上に作成されます。 高信頼 SharePoint アドインの顧客が、サイト サブスクリプション用に構成されたファームにアドインをインストールしようとしている場合、2 つの HighTrustConfig-*.ps1 スクリプトのどちらを使用していても、そのスクリプトを変更する必要があります。

サイト サブスクリプションにはそれぞれ独自の領域 ID がありますが、スクリプトの $realm = Get-SPAuthenticationRealm 行は、常にファームの領域を返します。 トークン発行元から発行されたアクセス トークンは、完全な発行元 ID の "@" 文字の後に指定される領域についてのみ、SharePoint によって有効と見なされます。

アドインをインストールする Web サイトの正しい領域を取得するには、スクリプトで Get-SPAuthenticationRealm を呼び出すときに、-ServiceContext パラメーターを使用する必要があります。 そうすると、サービス コンテキスト オブジェクトが、ターゲット Web サイトの親サイト コレクションから作成されます。

次に例を示しますが、この例の $WebURL は、http://marketing.contoso.com/sites/northteam/july など、SharePoint Web サイトの完全な URL を指定した文字列変数です。 このコードにより、指定された Web サイトだけでなく、同じサイト サブスクリプション内のすべての Web サイトで高信頼アドインを実行できるようになります。

$Web = Get-SPWeb $WebURL
$sc = Get-SPServiceContext -Site $Web.Site
$realm = Get-SPAuthenticationRealm -ServiceContext $sc

スクリプトの変更を完了するには、追加の必須パラメーター $WebURL を、ファイルの一番上にあるパラメーター リストに次のようにして追加します。

param (
  # other parameters omitted
  [Parameter()][String] $WebURL
)

新しいパラメーターに先行するパラメーターの後に、必ずコンマを追加してください。 また、新しいパラメーターを考慮に入れるため、一番上の行の "Usage" の例を次のように拡張してください。

-WebURL <full URL where SP add-in will be installed>

SharePoint アドインがすべてのサイト サブスクリプションで信頼されるようにするには、Get-SPFarm コマンドレットを使用してファームへの参照を取得してから、SiteSubscriptions プロパティを反復処理します。 各 SPSiteSubscription オブジェクトを、-SiteSubscription パラメーターの値として Get-SPServiceContext コマンドレットに渡します。 次に例を示します。

$Farm = Get-SPFarm
foreach ($ss in $Farm.SiteSubscriptions)
{
  $sc = Get-SPServiceContext -SiteSubscription $ss
  $realm = Get-SPAuthenticationRealm -ServiceContext $sc

  # All of the lines from the draft script below the call to
  # Get-SPAuthenticationRealm are inserted here inside the loop.
}
# end of script

関連項目