SharePoint アドインを登録する

Visual Studio、販売者ダッシュ ボード、または AppRegNew.aspx ページを使用して、Azure ACS に SharePoint アドインを登録し、登録情報を取得します。

重要

Azure Active Directory (Azure AD) のサービスである Azure アクセス制御 (ACS) は、2018 年 11 月 7 日に廃止されます。 SharePoint アドイン モデルでは、(この廃止の影響を受けない) https://accounts.accesscontrol.windows.net ホスト名を使用しているため、この廃止による影響はありません。 詳細については、「SharePoint アドインに対する Azure アクセス制御の終了の影響」を参照してください。

プロバイダー向けのホスト型 SharePoint アドインのリモート コンポーネントで OAuth を使用して SharePoint を操作するには、アドインをまず Azure ACS クラウド ベース サービスに登録し、テナンシーまたはファームの SharePoint アプリ管理サービスに登録する必要があります。 (これが "アプリ管理サービス" と呼ばれるのは、当初 SharePoint アドインが "SharePoint 用アプリ" と呼ばれていたためです)。

注:

これは、SharePoint ホスト型のアドインでは必要ありません。

アドインを Azure ACS に登録するには、次の情報を指定します。

• アドインの GUID。クライアント ID と呼ばれます。
• アドインのパスワード。クライアント シークレットと呼ばれます。
• ユーザーがアドインを信頼するよう求められる同意ページで使用するアドインの表示名。
• リモート アドインをホストするドメインの URL。
• リダイレクト URL。

アドインを登録すると、アドイン ID が割り当てられ、それはアドイン プリンシパルと呼ばれるセキュリティ プリンシパルになります。 ユーザーがアドインをインストールすると、SharePoint 管理者はその特定のアドイン プリンシパルに関する情報を取得できます。

SharePoint のリソースにアクセスするためのアクセス許可をユーザーが初めてアドインに付与すると (アドインの設計に応じて、アドインのインストール時、または実行時に発生します)、SharePoint は Azure ACS からそのアドインに関する情報を取得します。 次いで SharePoint はこの情報を、SharePoint のテナンシーまたはファームのアプリ管理サービス データベースに格納します。 クライアント シークレットは、Azure ACS でのみ格納されます。 SharePoint がアドインのシークレットを認識することはありません。 コンテンツ データベース サービスとその他のコンポーネント (ユーザー プロファイル サービスなど) は、アドインの表示名やその他の基本情報をアプリ管理共有サービスから直接取得できます。 詳細については、この記事の「アドイン登録情報とアドイン プリンシパル情報を取得する」を参照してください。

注:

この記事では、読者が OAuth 2.0 Framework の基礎となっている概念や原理を理解していることを前提としています。 詳細については、OAuth.net および Web 承認プロトコル (OAuth) を参照してください。

SharePoint アドインを Azure ACS に登録する

アドインを登録するには、アドイン開発のライフサイクルのどこにいるか、アドインのアーキテクチャ、およびどのように市場投入する計画なのかに応じて、次の 3 つの方法の 1 つを使用します。

登録方法	詳細
Visual Studio および Microsoft Office Developer Tools for Visual Studio を使用して、一時的なアドイン ID を作成する	Office Developer Tools for Visual Studio ウィザードが ACS と SharePoint テスト Web サイトのアプリ管理サービスを使用して、アドインの一時登録を作成します。 Visual Studio からアドインを実行 (F5 キー) するときに、この ID が使用されます。 また、このツールは、クライアント ID とシークレットを web.config ファイルと AppManifest.xml ファイルに挿入します。 アドインを発行する準備が整ったら、Visual Studio 発行ウィザードを使用して販売者ダッシュ ボードに移動し、それを登録できます。 SharePoint アドインを Office ストアで販売しない場合は、AppRegNew.aspx を使用してそれを登録します。 (実際の手順については次のセクションを参照。) 注: アドインがアドインのインストールではなく、実行時に SharePoint リソースに動的にアクセスするためのアクセス許可を要求した場合、Visual Studio を使用してアドイン ID を作成することはできません。
販売者ダッシュ ボード経由でアドインを登録する	アドインを複数の SharePoint テナントまたはファームで使用する場合は、Office ストアでアドインを販売するか、アドイン カタログを通して利用できるようにするかに関係なく、販売者ダッシュボードを使用してアドインを登録します。 販売者ダッシュボードに登録すると、アドインにマルチテナントのアーキテクチャを持たせた設計ができ、テナントまたはファームの管理者がアドインを個別に登録する必要がなくなります。 また、アドインを Office ストアに公開しようと計画している場合も、販売者ダッシュボードを使用してアドインを登録する必要があります。 販売者ダッシュボードに登録したアドインは、ストアを使用して公開する必要はありません。 詳細については、「販売者ダッシュボードでクライアント ID とクライアント シークレットを作成または更新する」を参照してください。
AppRegNew.aspx ページを使用する	SharePoint アドインを 1 つのテナントまたはファームでのみ使用する場合は、AppRegNew フォームを使用してアドインを登録します。 たとえば、単一の組織で使用するアドインを作成し、組織のアドイン カタログを使用してアドインを配布しようとしている場合は、テナンシーまたはファームの任意の Web サイトの AppRegNew.aspx ページを使用してアドインを登録できます。 AppRegNew.aspx を使用して登録したアドインは、Office ストア に公開することができません。 Office ストア に公開する予定のアドインについては、販売者ダッシュボード から ID を取得する必要があります。

AppRegNew.aspx を使用して登録するには

1. Web ブラウザーを使用して、<site collection url>/_layouts/15/AppRegNew.aspx に移動します。

   AppRegNew ページのフォーム

   

2. 次のフォーム フィールドに値を入力します。

   • アドイン ID。 クライアント ID とも呼ばれる GUID で、生成したり ([生成] を選択した場合)、AppRegNew.aspx に貼り付けたりできます。 値はアドインごとに一意である必要があり、小文字にする必要があります。

   • アドイン シークレット。 クライアント シークレットとも呼ばれる、中身の見えない文字列です。 [生成] ボタンを使用して AppRegNew.aspx ページ上で生成します。 アドイン シークレットの例を次に示します。xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=。

     重要

     アドイン シークレットには有効期限があります。 アドインを販売者ダッシュボードで登録する場合は、有効期限を最長で 3 年間まで設定できます。 古いシークレットの有効期限の日付に近づいたときに、ダッシュボードで新しいシークレットを追加することもできます。 新しいシークレットは、アドインのすべてのインスタンスで有効になります。 アドインを AppRegNew.aspx で登録する場合、シークレットの有効期限は 1 年で切れます。 詳細については、「SharePoint アドインで期限が切れたクライアント シークレットを置換する」を参照してください。

   • タイトル。 「Contoso 写真印刷アドイン」など、わかりやすいタイトルを指定します。 ユーザーは、アドインが要求しているアドインのアクセス許可を付与または拒否するように求められます。 このタイトルは、同意を求めるメッセージでアドインの名前として表示されます。

   • アドイン ドメイン。 SharePoint アドインのリモート コンポーネントのホスト名。 リモート アプリケーションがポート 443 を使用していない場合は、アドイン ドメインにポート番号も含める必要があります。 アドイン ドメインは、Web アプリケーションで使用する URL バインドと一致する必要があります。 この値にはプロトコル ("https:") や "/" の文字を含めないでください。 Web アプリケーションのホストが DNS CNAME エイリアスを使用している場合は、そのエイリアスを使用します。 次にいくつか例を示します。

     • www.contoso.com:3333
     • www.fabrikam.com

   • リダイレクト URI。 ACS が認証コードを送信するリモート アプリケーションまたはサービスのエンドポイント。 厳密に言えば、SharePoint アドインはこの値を使用しません。 リダイレクト URI が必要になるのは、SharePoint の外部で起動し、認証コード フローを使用して SharePoint データに対するアクセス許可を得る Web アプリケーションです。

     リダイレクト URI は、本当の意味での SharePoint アドイン (SharePoint から起動され、コンテキスト トークン フローを使用するもの) では無視されます。

     リダイレクト URI は通常、ACS から認証コードを要求したのと同じページ、コントローラー メソッド、または Web サービス メソッドですが、異なるエンドポイントにすることもできます。 エンドポイントは、ACS によって送信される HTTP 応答から認証コードを取得し、そのコードを使用してアクセス トークンと更新トークンを要求するロジックを持っている必要があります。 詳細については、「SharePoint アドインの認証コード OAuth フロー」を参照してください。

     このフォームには、本当の意味での SharePoint アドインの場合でも、有効な値を入力する必要があります (ただし、その値は使用されません)。 値は、プロトコル (HTTPS にしなければならない) を含む完全なエンドポイント URL にする必要があります。 次に例を示します。

     • https://www.contoso.com/Default.aspx
     • https://www.fabrikam.com/RedirectAccept.aspx
     • https://www.northwindtraders.com/home/index
     • https://adventureworks.com/

3. フォーム上の [作成] を選択します。 ページが再度読み込まれ、入力した値が確認のために表示されます。 コピーや貼り付けをしやすい形式で、これらの値を記録してください。 これらの値は、web.config ファイルと AppManifest.xml ファイルに入力するか、Visual Studio の発行ウィザードで入力する必要があります。

SharePoint アドインを登録する方法には関係なく、アドインをステージングまたは運用に展開する準備ができたら、登録値を web.config ファイルと AppManifest.xml ファイルに入力する必要があります。 ただし、Visual Studio では、Microsoft Office Developer Tools for Visual Studio によってこの構成が実行されます。

登録値を web.config ファイルと AppManifest.xml ファイルに入力する

SharePoint アドインをパッケージ化してリモート コンポーネントを展開する前に、登録する値のいくつかを AppManifest.xml ファイルと web.config ファイルに入力します。

ヒント

Visual Studio の発行ウィザードを使用して SharePoint アドインを発行する場合は、発行プロセスで、クライアント ID とクライアント シークレットを入力するように Visual Studio から要求されます。入力した情報は、自動的に正しい場所に入力されます。

1. Visual Studio プロジェクトの Web.config ファイルに、アドイン ID 値を ClientId 値として入力します (ツールによって入力された一時的な値を置き換えます)。

   重要

   クライアント ID の GUID の文字は、すべて小文字にする必要があります。

   次に例を示します。

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     .  .  .
   </appSettings>
   

2. アドイン シークレットの値を ClientSecret 値として入力します (ツールによって入力された一時的な値を置き換えます)。

   Web アプリケーションの Web.config ファイルでの値の使用方法の例を以下に示します。

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
   </appSettings>
   

3. Visual Studio プロジェクトの AppManifest.xml ファイルに、アドイン ID 値を ClientId 値として小文字で入力します。

   注:

   アドイン マニフェストは、SharePoint のリソースに対するアクセス許可を実行時に要求する Web アプリケーションには適用されません。 このようなアプリケーションは、本当の意味での "SharePoint アドイン" ではありません。 これらは、SharePoint にはインストールされず、アドイン マニフェストを持っていません。 詳細については、「SharePoint アドインの認証コード OAuth フロー」を参照してください。

   AppManifest.xml ファイルで ClientId 値を使用する例を次に示します。

   <AppPrincipal>
     <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
   </AppPrincipal>
   

4. Office Developer Tools for Visual Studio は、StartPage 要素でトークン ~remoteAppUrl を使用します。 (<StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage> など。) このトークンは、Visual Studio で発行ウィザードを使用している場合、リモート コンポーネントの URL に解決されます。 ウィザードを使用しない場合 (または、ウィザードを使用しても、リモート コンポーネントを Azure に発行している場合) には、アドインの登録時に使用した [アドイン ドメイン] の値に、このトークンを手動で置き換える必要があります。 これは、HTTPS プロトコルも含める以外は、ポート番号がある場合はそれも含めて、完全に同じ値でなければなりません。 次に例を示します。

   <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   

5. AppRegNew.aspx の [ タイトル] フィールドに使用したのと同じ値を、AppManifest.xml ファイルの Title 要素で使用することを検討します。 Title 要素の値は、アドインのインストール後に、ユーザーにアドインの名前として表示されます。 同意ダイアログに表示される名前と、SharePoint の UI とで名前が異なると、アドインのユーザーが混乱する恐れがあります。

   これらの値をアドイン マニフェストで指定する例を次に示します。

   <Properties>
     <Title>Contoso photo printing app</Title>
     <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   </Properties>
   

アクセス許可を実行時に求めるアドインでリダイレクト URL を使用する

Web アプリケーションが SharePoint の外部から起動する場合 (つまり、本当の意味での SharePoint アドインではない場合)、そのアドインは、実行時に SharePoint からアクセス許可を求めるように設計する必要があります。 このアドインには、リダイレクト URI やその他の情報を使用して ACS からアクセス トークンを取得するためのコードが必要です。 この URI が設定されている場所を見つけ、AppRegNew.aspx または販売者ダッシュボードの [リダイレクト URI] フィールドに使用した正確な値を使用します。 これは、コード ファイルや構成ファイルに含まれている場合があります。

アドイン登録情報とアドイン プリンシパル情報を取得する

SharePoint 上でインストールまたは登録したアドインに関するアドイン登録情報とアドイン プリンシパル情報を取得することができます。

登録したアドインに関する登録情報を調べるには、http://<SharePointWebsite>/_layouts/15/AppInv.aspx に移動します。

この情報を検索するには、アドインの登録に使用したクライアント ID (アドイン ID とも呼ばれる) を覚えておく必要があります。 この検索により、特定のクライアント ID について次の情報が返されます。

• タイトル
• アドイン ドメイン
• リダイレクト URL (リダイレクト URI と同じもの)

この検索では、アドイン シークレットの値は返されません。

登録済みのアドイン プリンシパルの一覧を表示するには、http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx に移動します。

関連項目

• SharePoint アドインの 3 つの承認システム
• プロバイダー ホスト型 SharePoint アドインの作成を始める
• SharePoint アドインの承認と認証