SharePoint の高信頼性アドインを作成する

[アーティクル]
04/08/2023

高信頼アドインは、プロバイダー向けのホスト型の SharePoint アドインであり、デジタル証明書を使用してリモート Web アプリケーションと SharePoint の間の信頼を確立します。 "高信頼" と "完全な信頼" は同義ではありません。高信頼アドインであっても、アドインのアクセス許可を要求する必要があります。このアドインが "高信頼" と見なされるのは、アドインに必要な任意のユーザー ID を使用する信任を得ており、SharePoint に渡すアクセストークンのユーザー部分をこのアドインが担当して作成するからです。

高信頼 SharePoint アドインは、主にオンプレミス環境での使用を目的としています。高信頼アドインを Microsoft SharePoint Online にインストールすることはできず、通常は、リモートコンポーネントもオンプレミスで企業ファイアウォール内にインストールされます。したがって、SharePoint アドインのインスタンスは個々の企業に固有のものになります。

高信頼アドインは、コンテキストトークンの代わりに証明書を使用して信頼を確立します。 (信頼ブローカーを高信頼アプリとして機能させるために変更する必要がある、Microsoft Azure Access Control Service (ACS) を使用するように構築されたプロバイダーホスト型アドイン)。高信頼アドインでは、SharePoint ファームとリモート Web アプリケーションをホストしているサーバーで、いくつかの構成が必要です。

SharePoint では、サーバー間セキュリティトークンサービス (STS) によってサーバー間認証のためのアクセストークンが提供されます。サーバー間 STS により、一時的なアクセストークンを使用して、Exchange、Lync、SharePoint のアドインなど、他のアプリケーションサービスにアクセスできます。アプリケーションサービス間の信頼を確立するには (たとえば、SharePoint とリモートアドインの間の信頼の確立など)、Windows PowerShell コマンドレットと証明書を使用します。

注:

サーバー間 STS は、ユーザー認証用のサービスではありません。したがって、サーバーの全体管理の [認証プロバイダー] セクションや SharePoint のユーザー選択ウィンドウの、ユーザーサインインページにサーバー間 STS は表示されません。

この記事では、高信頼アドインの作成方法を示し、F5 キーを選択して Visual Studio 内でそのアドインを実行するための設定手順を説明します。内容は次のとおりです。

高信頼アドインとして使用するためのアドインを構成する。
高信頼アドインを使用するように SharePoint を構成する。
基本的な高信頼アドインを作成する。

テスト環境、ステージング環境、運用環境の構成は、それぞれいくらか異なっており、これについては「高信頼 SharePoint アドインをパッケージ化して発行する」で説明しています。

前提条件

この資料の手順に従うには、以下が整っていることを確認してください。

オンプレミスの SharePoint 開発環境。セットアップの手順については、「SharePoint アドインのオンプレミスの開発環境をセットアップする」を参照してください。特に、「SharePoint のサービスをサーバー間アドインで使用するために構成する」のセクションにある手順を必ず完了します。
プロバイダーホスト型 SharePoint アドインの作成経験。「プロバイダー向けのホスト型 SharePoint アドインの作成を始める」を参照してください。
Visual Studio がリモート、または SharePoint をインストールしたコンピューターにインストールされていること。
バリアント型 (Microsoft Office Developer Tools for Visual Studio) の値を使用します。
デジタル証明書とその使用方法に関する知識。参照先:
- デジタル証明書
- 証明書の使用

証明書を入手するか、パブリックとプライベートのテスト証明書を作成する

高信頼アドインのリモート Web アプリケーションには、X.509 デジタル証明書が必要です。 SharePoint アドインを完全にテストするには、ドメインで発行された証明書、または証明機関によって発行された商用証明書が必要です。ただし、デバッグの初期段階では、自己署名証明書を使用できます。

次の手順で、IIS を使用してテスト証明書を作成し、エクスポートする方法を示します。自己署名証明書をドメインで発行された証明書または商用証明書で置き換える手順については、後の「ドメインで発行された証明書または商用証明書を使用してデバッグを完了する」セクションで説明します。

あるいは、MakeCert テストプログラムを使用して、X.509 証明書を生成することもできます。 MakeCert の使用方法の詳細については、「Authenticode を使用したコードの署名およびチェック」を参照してください。

最初にテスト用の .pfx 証明書ファイルを作成してから、対応するテスト用 .cer ファイルを作成します。 .pfx 証明書には秘密キーが含まれていて、SharePoint への通信に署名するためにリモート Web アプリケーションによって使用されます。 .cer には公開キーが含まれています。SharePoint はそれを使用して、メッセージの暗号化を解除し、それがリモート Web アプリケーションからのものであることを確認し、SharePoint が信頼するトークン発行者からのアクセストークンがリモート Web アプリケーションにあることを確認します。 .pfx ファイルと .cer ファイルの詳細については、「ソフトウェア発行者の証明書」を参照してください。

テスト用の自己署名入り .pfx 証明書ファイルを作成するには

高信頼 SharePoint アドインを Visual Studio でデバッグする場合、リモート Web アプリケーションは Visual Studio がインストールされているコンピューターの IIS Express でホストされます。したがって、そのリモート Web アプリケーションコンピューターには、証明書を作成できる IIS マネージャーがありません。このため、SharePoint テストサーバーで IIS を使用して証明書を作成します。

IIS マネージャーの左側のツリービューで、サーバー名ノードを選択します。

次の図に示すように、[サーバー証明書] アイコンを選択します。

IIS のサーバー証明書オプション

右側のリンクセットから [自己署名入り証明書の作成] リンクを選択します。

自己署名入り証明書リンクを作成する

証明書に「HighTrustSampleCert」という名前を付け、[OK] を選択します。
証明書を右クリックして、[エクスポート] を選択します。

テスト証明書をエクスポートする

Windows またはコマンドラインで、C:\Certs という名前のフォルダーを作成します。
IIS マネージャーに戻り、ファイルを C:\Certs にエクスポートして、パスワードを設定します。この例では、パスワードは password です。
テスト用の SharePoint インストールが、Visual Studio が実行されているコンピューターと同じコンピューター上にない場合は、Visual Studio コンピューターにフォルダー C:\Certs を作成し、HighTrustSampleCert.pfx ファイルを移動します。これは、Visual Studio でデバッグを行うときにリモート Web アプリケーションが実行されるコンピューターです。

対応する .cer ファイルを作成するには

SharePoint サーバーで、次の IIS アドインプールのアドインプール ID に、C:\Certs フォルダーへの読み取り権限があることを確認します。

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

IIS マネージャーの左側のツリービューで、サーバー名ノードを選択します。
[サーバー証明書] をダブルクリックします。
[サーバー証明書] ビューで、[HighTrustSampleCert] をダブルクリックして、証明書の詳細を表示します。
[詳細] タブで [ファイルにコピー] を選択して、証明書エクスポートウィザードを起動し、[次へ] を選択します。
既定値の [いいえ、秘密キーをエクスポートしません] を使用し、[次へ] を選択します。
既定値を使用して、[次へ] を選択します。
[参照] を選択して C:\Certs を参照し、証明書に「HighTrustSampleCert」という名前を付け、[保存] を選択します。証明書は .cer ファイルとして保存されます。
[次へ] を選択します。
[完了] を選択します。

証明書を使用するように SharePoint を構成し、アドインに対する信頼を構成する

このセクションで作成する Windows PowerShell スクリプトは、Visual Studio で F5 キーの使用をサポートすることを目的としています。そのスクリプトでは、ステージングまたは運用 SharePoint インストールは、正しく構成されません。証明書を使用するように運用 SharePoint を構成する手順については、「高信頼 SharePoint アドインをパッケージ化して発行する」を参照してください。

重要

この記事の前提条件に含まれていた「SharePoint のサービスをサーバー間アドインで使用するために構成する」の手順が完了していることを、再度確認します。完了していない場合は、先に進む前に、この時点で構成を行う必要があります。

SharePoint を構成するには

テキストエディターまたは Windows PowerShell エディターで、新しいファイルを作成し、次の行を追加して証明書オブジェクトを作成します。

  $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
  $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)

次の行を追加して、SharePoint が証明書をルート証明機関として扱うようにします。

  New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate

認証レルムの ID を取得するには次の行を追加します。

  $realm = Get-SPAuthenticationRealm

リモート Web アプリケーションは、アクセストークンを使用して SharePoint データへアクセスします。アクセストークンは、SharePoint が信頼しているトークン発行者によって発行される必要があります。高信頼 SharePoint アドインの場合、この証明書がトークン発行者です。次の行を追加して、SharePoint で必要な形式で発行者 ID を作成 します:_specific_issuer_GUID_@_realm_GUID_。

  $specificIssuerId = "11111111-1111-1111-1111-111111111111"
  $fullIssuerIdentifier = $specificIssuerId + '@' + $realm

注:

運用環境では証明書ごとに固有の発行者が必要になるため、$specificIssuerId 値は GUID である必要があります。ただし、同じ証明書を使用してすべての高信頼アドインをデバッグする今回のコンテキストでは、値をハードコーディングできます。何らかの理由で、ここで使用されているものとは異なる GUID を使用する場合は、GUID のすべての文字が小文字であることを確認します。現在、SharePoint のインフラストラクチャでは、証明書の発行者 GUID が小文字である必要があります。

次の行を追加して、証明書を信頼されたトークン発行者として登録します。 -Name パラメーターは一意である必要があるため、運用構成では名前の一部 (またはすべて) として GUID を使用するのが一般的ですが、このコンテキストではわかりやすい名前を使用できます。 -IsTrustBroker スイッチは、開発するすべての高信頼アドインに同じ証明書を使用できるようにするために必要です。トークン発行者をすぐに登録するには、iisreset コマンドが必要です。このコマンドがないと、新しい発行者が登録されるまでに最大 24 時間待たなければならない場合があります。

  New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
  iisreset

通常、SharePoint は自己署名証明書を受け入れません。したがって、デバッグ用に自己署名証明書を使用するときは、次の行を追加して、リモート Web アプリケーションが SharePoint を呼び出すときに HTTPS を使用するという、SharePoint の通常の要件を無効にします。そうしない場合、リモート Web アプリケーションが自己署名証明書を使用して SharePoint を呼び出すときに "403 (forbidden)" メッセージが表示されます。これは後の手順で元に戻します。 HTTPS 要件を無効にすることで、リモート Web アプリケーションから SharePoint への要求は暗号化されませんが、証明書はアクセストークンの信頼された発行者として引き続き使用されます。これは高信頼 SharePoint アドインの主要な目的です。

  $serviceConfig = Get-SPSecurityTokenServiceConfig
  $serviceConfig.AllowOAuthOverHttp = $true
  $serviceConfig.Update()

HighTrustConfig-ForDebugOnly.ps1 という名前でファイルを保存します。
管理者として SharePoint 管理シェルを開き、次の行によってファイルを実行します。

  ./HighTrustConfig-ForDebugOnly.ps1

高信頼 SharePoint アドインを作成する

このセクションでは、Visual Studio を使用して高信頼 SharePoint アドインを作成します。

注:

「高信頼アドインを作成するための前提条件」セクションで述べたように、この記事の内容はプロバイダー向けのホスト型 SharePoint アドインの作成方法に関する知識を前提としています。詳細については、「プロバイダー向けのホスト型 SharePoint アドインの作成を始める」を参照してください。

高信頼 SharePoint アドインを作成するには

Visual Studio で、[ファイル]>[新規作成]>[プロジェクト] を選択します。
[新しいプロジェクト] ウィザードで、Visual C# または Visual Basic ノードを展開し、次に Office/SharePoint ノードを展開します。
[アドイン] を選択し、次に SharePoint 用アドイン プロジェクトの作成を選択します。
プロジェクトに「HighTrustSampleApp」という名前を付けます。
任意の場所にプロジェクトを保存し、[OK] を選択します。
SharePoint 開発者向けのサイトの完全な URL を指定します。たとえば、http://TestServer/sites/devsite/ のように指定します。
[プロバイダー向けのホスト型] オプションを選択し、[次へ] を選択します。
Web プロジェクトの種類を指定するように求められたら、このトピックの継続的な例では [ASP.NET Web Forms アプリケーション] を選択してから、[次へ] を選択します。
ウィザードの [認証設定を構成する] ページが開きます。このフォームに追加する値は、自動的に Web.config ファイルに追加されます。 [アドインの認証方法] で、[証明書を使用する] を選択します。
[証明書の場所] ボックスの横の [参照] をクリックし、作成した自己署名証明書 (.pfx ファイル) の場所 (C:\Certs) に移動します。このフィールドの値は完全なパス C:\Certs\HighTrustSampleCert.pfx である必要があります。
[パスワード] ボックスに、この証明書のパスワードを入力します。この場合、「password」と入力します。
[発行者 ID] ボックスに、発行者 ID (11111111-1111-1111-1111-111111111111) を入力します。
[完了] を選択します。構成の大半は、ソリューションを開いたときに実行されます。 Visual Studio ソリューション内に 2 つのプロジェクトが作成されます。1 つは SharePoint アドインのプロジェクトで、もう 1 つは ASP.NET Web アプリケーションのプロジェクトです。

アドインを実行してデバッグするには

Office Developer Tools for Visual Studio は、ASP.NET プロジェクトが作成されたときに、default.aspx ファイルと default.aspx.cs ファイルを自動的に生成します。生成されたコードは SharePoint ホスト Web のタイトルを取得し、リモート Web アプリケーションの既定のページにそのタイトルを出力します。これらのファイルの実際のマークアップとコードは、ツールのバージョンによって異なります。このトピックでは、生成された default.aspx ファイルと default.aspx.cs ファイルを変更することなく使用します。
SharePoint アドインとそのリモート Web アプリケーションをテストするには、Visual Studio で F5 キーを選択します。 Web アプリケーションは localhost で IIS Express に展開されます。 SharePoint アドインはターゲット SharePoint Web サイトにインストールされます。 SharePoint からは、SharePoint アドインが要求するアクセス許可を付与するように求めるメッセージが表示されます。 Office Developer Tools for Visual Studio のバージョンによって、アドインがすぐに起動されるものと、ターゲット SharePoint Web サイトの [サイトコンテンツ] ページが開いて、そこに新しいアドインが一覧表示されるものがあります。

自動的に起動されていない場合は、アドインを起動します。リモート Web アプリケーションが起動し、AppManifest.xml ファイル (Default.aspx) で開始ページとして指定したページが開きます。アドインは、次の図のように表示されます。

Web タイトルを取得するサンプルアプリ

ドメインで発行された証明書または商用証明書を使用してデバッグを完了する

以前に作成した Windows PowerShell スクリプトにより、リモート Web アプリケーションは HTTPS プロトコルを使用して SharePoint にアクセスするという SharePoint の通常の要件が無効になりました。 HTTPS をオフにして作業を行うと、HTTPS が要求される運用展開の際に発生する可能性のある特定の問題を、アドインのビルド時点で見逃すことになりかねません。したがって、テスト証明書をドメインで発行された証明書または商用証明書で置き換え、HTTPS 要件を有効にしてアドインを再起動するまでは、開発とデバッグフェーズが完了したと見なすことはできません。

新しい証明書を入手したら、まだ追加していない場合は証明書にパスワードを追加する必要があります。運用環境では強力なパスワードを使用しますが、SharePoint アドインのデバッグには任意のパスワードを使用できます。 pfx および cer の 2 つの形式の証明書が必要です。取得したときに pfx 形式でない場合は、ユーティリティを使用して pfx に変換することが必要な場合があります。 pfx ファイルがある場合は、次の手順に従って IIS にインポートし、cer ファイルをエクスポートできます。

新しい証明書をインポートするには

.pfx ファイルを SharePoint サーバー上の C:\Certs に配置します。この記事では、ファイルの名前が "MyCert.pfx" であると想定しています。すべての手順の "MyCert" を、証明書の実際の名前に置き換えてください。
IIS マネージャーの左側のツリービューで、サーバー名ノードを選択します。
[サーバー証明書] アイコンをダブルクリックします。
右側の [アクション] ウィンドウで、[インポート] を選択します。
[証明書のインポート] ダイアログで、参照ボタンを使用して C:\Certs\MyCert.pfx を参照し、次に証明書のパスワードを入力します。
[この証明書のエクスポートを許可する] がオンになっていることを確認し、[OK] を選択します。
[サーバー証明書] のリストで証明書を右クリックし、[エクスポート] を選択します。
C:\Certs にファイルをエクスポートし、そのパスワードを指定します。
テスト用の SharePoint インストールが、Visual Studio が実行されているコンピューターと同じコンピューター上にない場合は、 MyCert.pfx ファイルを Visual Studio コンピューターの C:\Certs フォルダーに移動します。
[サーバー証明書] ビューで、MyCert をダブルクリックして、証明書の詳細を表示します。
[詳細] タブで [ファイルにコピー] を選択して、証明書エクスポートウィザードを起動し、[次へ] を選択します。
既定値の [いいえ、秘密キーをエクスポートしません] を使用し、[次へ] を選択します。
既定値を使用します。 [次へ] を選択します。
[参照] を選択して C:\Certs を参照し、証明書に「MyCert」という名前を付け、[保存] を選択します。証明書は .cer ファイルとして保存されます。
[次へ] を選択します。
[完了] を選択します。

新しい証明書を使用するように SharePoint を構成するには

HighTrustConfig-ForDebugOnly.ps1 ファイルを編集用に開き、次の変更を行います。

MyCert と表示される両方の場所で HighTrustSampleCert を置き換えます。
特定の発行者 ID 11111111-1111-1111-1111-111111111111 を 22222222-2222-2222-2222-222222222222 に置き換えます。
"High Trust Sample Cert" を "My Cert" またはその他の適切なわかりやすい名前に置き換えます。
$serviceConfig.AllowOAuthOverHttp = $true 行で、true を false に置き換えます。これにより、HTTPS を使用しなければならないという要件が再び有効になります。

ファイルを保存します。
管理者として SharePoint 管理シェルを開き、次の行によってファイルを実行します。

  ./HighTrustConfig-ForDebugOnly.ps1

リモート Web アプリケーションを再構成するには

Visual Studio で、Web アプリケーションプロジェクトの web.config ファイルを開き、次の変更を行います。

ClientSigningCertificatePath キーで、C:\Certs\HighTrustSampleCert.pfx を C:\Certs\<MyCert>.pfx に置き換えます。
ClientSigningCertificatePassword キー値を証明書の実際のパスワードに置き換えます。
IssuerId キー値を 22222222-2222-2222-2222-222222222222 に置き換えます。

F5 キーを選択して、アドインをデバッグします。

高信頼アドインの開発が終了したら、「高信頼 SharePoint アドインをパッケージ化して発行する」を参照し、この種の SharePoint アドインをパッケージ化および発行する方法を確認してください。

TokenHelper および SharePointContext ファイルの機能

Office Developer Tools for Visual Studio には、リモート Web アプリケーションに TokenHelper.cs (または .vb) ファイルが含まれています。また、一部のバージョンのツールに SharePointContext.cs (または .vb) ファイルが含まれています。

これらのファイルのコードは、次の操作を実行します。

ネットワーク呼び出しを行うときに証明書を信頼するように .NET を構成します。
指定された WindowsIdentity オブジェクトの代わりにリモート Web アプリケーションのプライベート証明書によって署名され、SharePoint が信頼関係を確立するために使用する、サーバー間アクセストークンを取得します。
SharePoint セキュリティトークンサービス (STS) 証明書を取得します。
高信頼承認システムではなく低信頼承認システムを使用するアドインの場合、これらのファイルには「SharePoint のアドインのコンテキストトークン OAuth フロー」で説明されているシナリオ用の OAuth トークン処理など、追加のタスクがあります。そのシナリオはこの記事では扱いません。

高信頼アドインには、コンテキストトークンがありません。コンテキストトークンは、低信頼の承認を使用する構成に固有のものです。ただし、それでもアクセストークンは必要です。高信頼の構成を使用している場合、Web アプリケーションは SharePoint と同じ方法でユーザーを認証する必要があります (つまり、ユーザーおよび ID プロバイダーの ID を含むアクセストークンをアドインの責任で作成する必要があります)。

Visual Studio で F5 キーを使用してデバッグを行う場合、Microsoft Office Developer Tools for Visual Studio は Windows 認証を使用し、生成される 2 つのコードファイルがアドインを実行しているユーザーの Windows ID を使用してアクセストークンを作成します。アドインを発行するとき、生成されたこれらの 2 つのファイルを変更せずに使用するには、Windows 認証を使用するようにリモート Web アプリケーションを IIS マネージャーで構成する必要があります。

アドインが運用環境で Windows 認証を使用しない場合は、生成されたコードファイル TokenHelper または SharePointContext (あるいはその両方) をカスタマイズして、別の認証システムを使用する必要があります。 SharePoint アドインを実行しているユーザーとは別の ID でリモート Web アプリケーションが SharePoint にアクセスする場合も、これらのファイルをカスタマイズします。最後に、リモート Web アプリケーションが PHP、node.js、Java、その他の非 ASP.NET プラットフォームである場合には、コードによって、使用している認証システムからユーザー ID を取得し、作成されるアクセストークンにその ID を追加する必要があります。