SharePoint アドインのコンテキスト トークン OAUTH フロー
SharePoint では、プロバイダー向けのホスト型の低信頼性アドインの OAuth 認証と承認フローにユーザーのアドイン、SharePoint、承認サーバー、およびブラウザーの間で実行時に行われる一連の対話が含まれます。 このシナリオの認証サーバーは、Microsoft Azure Access Control Service (ACS) です。
重要
Azure Active Directory (Azure AD) のサービスである Azure アクセス制御 (ACS) は、2018 年 11 月 7 日に廃止されます。 SharePoint アドイン モデルでは、(この廃止の影響を受けない) https://accounts.accesscontrol.windows.net ホスト名を使用しているため、この廃止による影響はありません。 詳細については、「SharePoint アドインに対する Azure アクセス制御の終了の影響」を参照してください。
プロバイダー向けのホスト型アドインには、SharePoint とは別個の、また SharePoint ファームや SharePoint Online テナントの一部ではない、リモート Web アプリケーションまたはサービスがあります。 それは、クラウドで、またはオンプレミスのサーバーでホストすることができます。 この記事では、リモート コンポーネントを Contoso.com と呼ぶことにします。
注:
リモート コンポーネントは、SharePoint 項目 (リストやリスト項目など) に発生したイベントに応答するイベント レシーバーをホストすることもできます。 Contoso.com が応答できるリモート イベントの例として、リスト イベント (リスト項目の追加や削除など) や、Web イベント (サイトの追加や削除など) があります。 リモート イベント レシーバーを作成する方法の詳細については、「SharePoint アドインでリモート イベント レシーバーを作成する」を参照してください。
Contoso.com では、SharePoint クライアント オブジェクト モデル (CSOM) または SharePoint REST API を使用して、SharePoint への呼び出しを行います。 Contoso.com アプリケーションは、OAuth のトークン受け渡しフローを使用して SharePoint で認証を行います。 SharePoint と Contoso.com は相互に信頼していませんが、どちらも ACS を信頼しているため、ACS によって発行されたトークンを受け入れます。
関係するトークンは 3 つあります。ACS は SharePoint のためにコンテキスト トークンを作成します。SharePoint は、このトークンを Constoso.com に転送します。 Contoso.com は、コンテキスト トークンが ACS によって発行されたものであることを検証し、そうであればそのトークンを信頼します。 その後、Contoso.com は、コンテキスト トークンから更新トークンを抽出し、それを使用してアクセス トークンを ACS から直接取得します。 Contoso.com は SharePoint に対するすべての要求にこのアクセス トークンを含めます。 SharePoint は、アクセス トークンが ACS によって発行されたものであることを検証し、そうであれば Contoso.com からの要求に応答します。
リモート コンポーネントにトークン処理コードを記述します (ただし、リモート コンポーネントが .NET にホストされている場合、Microsoft Office Developer Tools for Visual Studio によってサンプル コードが提供されており、これが大部分の処理を行います)。 トークンの処理コードの詳細については、「プロバイダー向けのホスト型の低信頼 SharePoint アドインでセキュリティ トークンを処理する」を参照してください。
前提条件
SharePoint アドインでコンテキスト トークン フローを使用可能にするには、事前に次の予備的な手順を完了しておく必要があります。
次の要件は、SharePoint Online に加えてオンプレミスで SharePoint アドインをインストールする場合にのみ適用されます。SharePoint アドインを SharePoint Online にインストールしている場合、これらの要件は適用されません。
- アドインをサポートするようにファームを構成する必要があります。これは、実際には、コンテキスト トークン フローを使用しない場合も含め、すべての SharePoint アドインをファームにインストールする場合の要件です。 詳細については、「SharePoint アドインを開発するためのツールと環境」を参照してください。
- アドインをインストールするお客様は、Office 365 アカウントを持っている必要があります。 これは ACS にアクセスするために必要です。 お客様は、他の目的のために自分のアカウントを使用する必要はありません。
- Office 365 が ACS に対して持つ信頼関係を共有するようにファームを構成する必要があります。 これは、Windows PowerShell スクリプトを使用して簡単に行えます。 詳細については、「Office 365 SharePoint サイトを使用してオンプレミスの SharePoint サイトのプロバイダー向けのホスト型アドインに権限を付与する」を参照してください。
アドインを SharePoint Online にインストールするか、オンプレミスの SharePoint ファームにインストールするかに関わらず、SharePoint アドインを ACS に登録する必要があります。 これを実行する方法の詳細については、「SharePoint アドインを登録する」を参照してください。登録の一環として、アドインは ACS にクライアント ID とクライアント シークレットなどを提供します。
OAuth コンテキスト トークン フローの手順
次の図に、SharePoint プロバイダー向けのホスト型アドインの OAuth 認証と承認フローを示します。
OAuth コンテキスト トークン フロー
図中の番号に対応する手順は次のとおりです。
ユーザーが SharePoint アドインを SharePoint から起動します。 これが実行される方法は、アドインの設計によって決まります。
- アドインがアドイン パーツ (実質的には IFRAME を囲むラッパー) 内のリモート Web アプリケーション (Contoso.com にある) を表示するように設計されている場合、アドインの起動は、アドイン パーツの含まれる SharePoint ページに移動するだけで行えます。 (ユーザーがまだサインインしていない場合は、ユーザーがサインインするように SharePoint からメッセージが出ます。) SharePoint がページを処理し、ページ上に Contoso.com アプリケーションからのコンポーネントがあることを検出します。 (アドイン パーツの詳細については、「アドイン パーツを作成して SharePoint アドインと共にインストールする」を参照してください。)
- アドインがブラウザー内のページ全体を使用するように設計されている場合、ユーザーがそのアドインを起動するには、SharePoint の Web サイトの [サイト コンテンツ] ページにあるアドイン タイルを選択します。 (他のバリエーションとして、リモート コンポーネントを起動するカスタム メニューやリボン項目がアドインに組み込まれている場合があります。)
アドインを起動する方法にかかわらず、SharePoint は Contoso.com アプリケーションに送信できるコンテキスト トークンを取得する必要があります。そのため、SharePoint コンテキストに関する情報 (現在のユーザー、リモート アプリケーション URL、その他) を格納するコンテキストトークンを作成するように ACS に依頼します。 コンテキスト トークンには、暗号化されたリフレッシュ トークンも含まれています。
ACS は、Contoso.com のアドイン シークレットを使ったアルゴリズムを使用してコンテキスト トークンに署名し、それを SharePoint に返信します。 ACS と Contoso.com アドインだけがシークレットを知っています。
Contoso.com アプリケーションがアドイン パーツに表示される場合、SharePoint は、アドイン パーツをホストするページをレンダリングし、アドイン パーツ内の IFRAME がコンテンツを取得するために呼び出す URL にコンテキスト トークンを追加します。 Contoso.com アプリケーションがページ全体の場合、SharePoint はブラウザーを Constoso.com にリダイレクトし、リダイレクト応答の一部としてコンテキスト トークンを組み込みます。
コンテキスト トークンは、Contoso.com サーバーに送信されるブラウザー要求に組み込まれます。
Contoso.com サーバーは、コンテキスト トークンを受け取り、署名を検証します (これを実行できるのは、クライアント シークレットを知っているからです)。 これにより、Contoso.com は、トークンが ACS によって発行されたものであり、SharePoint を詐称する第三者から発行されたものではないことを確認できます。 Contoso.com は、コンテキスト トークンから更新トークンを抽出し、そのトークンをクライアント ID やクライアント シークレットなどの他の情報と一緒に ACS に送信して、SharePoint にアクセスするためのアクセス トークンを要求します。
ACS は、更新トークンを検証してトークンを発行したことを確認し、Contoso.com にアクセス トークンを返します。 必要に応じて、Contoso.com は、このアクセス トークンをキャッシュすることができます。これにより、SharePoint にアクセスするたびに ACS にアクセス トークンを要求する必要がなくなります。 既定では、アクセス トークンは一度に数時間は有効です。 (この記事の執筆の時点では、ACS が SharePoint に発行するアクセス トークンの既定の有効期間は 12 時間ですが、これは変更される可能性があります。)
各アクセス トークンは、承認を求める最初の要求で指定されたユーザー アカウントに固有のもので、その要求で指定されたサービス (この場合は SharePoint) に対するアクセス許可のみを付与します。 リフレッシュ トークンの有効期限はさらに長くなっており (この記事の執筆の時点では 6 か月)、これもキャッシュすることができます。 したがって、リフレッシュ トークンそのものが期限切れになるまでは、同じリフレッシュ トークンを ACS からの新しいアクセス トークンに対して再利用できます。 (トークンのキャッシュの詳細については、「プロバイダー向けのホスト型の低信頼 SharePoint アドインでセキュリティ トークンを処理する」を参照してください。)
リフレッシュ トークンが期限切れになると、Contoso.com は新しいコンテキスト トークンを取得することによって新しいリフレッシュ トークンを取得できます。 詳細については、「新しいコンテキスト トークンを取得する」を参照してください。
- Contoso.com は、アクセス トークンを使用して SharePoint REST API 呼び出しを行うか、spnv に CSOM 要求を出します。 これは HTTP Authorization ヘッダーに入れて OAuth アクセス トークンを渡すことによって行われます。 (お使いのリモート コンポーネントが .NET プラットフォームでホストされている場合、ヘッダーを作成するサンプル コードが Office Developer Tools for Visual Studio に添付されています。)
- SharePoint は、アクセス トークンを検証し、トークンが ACS によって発行されたものであることを確認します。 その後、Contoso.com から要求されたデータを Contoso.com に送信するか、Contoso.com から要求された作成、読み取り、更新、削除 (CRUD) 操作を実行します。
- Contoso.com アプリケーションのページがブラウザー (または、アドイン パーツの IFRAME) 内でレンダリングされます。