SharePoint アドインのコンテキスト トークン OAUTH フローContext Token OAuth flow for SharePoint Add-ins

SharePoint では、プロバイダー向けのホスト型の低信頼性アドインの OAuth 認証と承認フローにユーザーのアドイン、SharePoint、承認サーバー、およびブラウザーの間で実行時に行われる一連の対話が含まれます。In SharePoint, the OAuth authentication and authorization flow for a provider-hosted, low-trust, add-in involves a series of interactions among your add-in, SharePoint, the authorization server, and the browser at runtime. このシナリオの認証サーバーは、Microsoft Azure Access Control Service (ACS) です。The authorization server in this scenario is Microsoft Azure Access Control Service (ACS).

重要

Azure Active Directory (Azure AD) のサービスである Azure アクセス制御 (ACS) は、2018 年 11 月 7 日に廃止されます。Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. SharePoint アドイン モデルでは、(この廃止の影響を受けない) https://accounts.accesscontrol.windows.net ホスト名を使用しているため、この廃止による影響はありません。This retirement does not impact the SharePoint Add-in model, which uses the https://accounts.accesscontrol.windows.net hostname (which is not impacted by this retirement). 詳細については、「SharePoint アドインに対する Azure アクセス制御の終了の影響」を参照してください。For more information, see Impact of Azure Access Control retirement for SharePoint Add-ins.

プロバイダー向けのホスト型アドインには、SharePoint とは別個の、また SharePoint ファームや SharePoint Online テナントの一部ではない、リモート Web アプリケーションまたはサービスがあります。With a provider-hosted add-in, you have a remote web application or service that is separate from SharePoint, and not part of the SharePoint farm or SharePoint Online tenancy. それは、クラウドで、またはオンプレミスのサーバーでホストすることができます。It can be hosted in the cloud or on an on-premises server. この記事では、リモート コンポーネントを Contoso.com と呼ぶことにします。In this article, the remote component is called Contoso.com.

注意

リモート コンポーネントは、SharePoint 項目 (リストやリスト項目など) に発生したイベントに応答するイベント レシーバーをホストすることもできます。The remote component can also host event receivers that respond to events that occur to SharePoint items, such as lists or list items. Contoso.com が応答できるリモート イベントの例として、リスト イベント (リスト項目の追加や削除など) や、Web イベント (サイトの追加や削除など) があります。Examples of remote events that Contoso.com might want to respond to are list events, such as adding or removing a list item; or web events, such as adding or deleting a site. リモート イベント レシーバーを作成する方法の詳細については、「SharePoint アドインでリモート イベント レシーバーを作成する」を参照してください。For more information about how to create remote event receivers, see Create a remote event receiver in SharePoint Add-ins.

Contoso.com では、SharePoint クライアント オブジェクト モデル (CSOM) または SharePoint REST API を使用して、SharePoint への呼び出しを行います。Contoso.com uses the SharePoint client object model (CSOM) or the SharePoint REST APIs to make calls to SharePoint. Contoso.com アプリケーションは、OAuth のトークン受け渡しフローを使用して SharePoint で認証を行います。The Contoso.com application uses an OAuth token-passing flow to authenticate with SharePoint. SharePoint と Contoso.com は相互に信頼していませんが、どちらも ACS を信頼しているため、ACS によって発行されたトークンを受け入れます。SharePoint and Contoso.com do not trust each other; but both trust ACS and accept tokens issued by ACS.

関係するトークンは 3 つあります。ACS は SharePoint のためにコンテキスト トークンを作成します。SharePoint は、このトークンを Constoso.com に転送します。There are three tokens involved: SharePoint has ACS create a context token that SharePoint forwards to Constoso.com. Contoso.com は、コンテキスト トークンが ACS によって発行されたものであることを検証し、そうであればそのトークンを信頼します。Contoso.com validates that the context token was issued by ACS so it trusts it. その後、Contoso.com は、コンテキスト トークンから更新トークンを抽出し、それを使用してアクセス トークンを ACS から直接取得します。Contoso.com then extracts a refresh token from the context token and uses it to get an access token directly from ACS. Contoso.com は SharePoint に対するすべての要求にこのアクセス トークンを含めます。It includes the access token in all its requests to SharePoint. SharePoint は、アクセス トークンが ACS によって発行されたものであることを検証し、そうであれば Contoso.com からの要求に応答します。SharePoint validates that the access token was issued by ACS, so it responds to the requests from Contoso.com.

リモート コンポーネントにトークン処理コードを記述します (ただし、リモート コンポーネントが .NET にホストされている場合、Microsoft Office Developer Tools for Visual Studio によってサンプル コードが提供されており、これが大部分の処理を行います)。You provide the token-handling code in the remote component (but if your remote component is hosted on .NET, the Microsoft Office Developer Tools for Visual Studio provide sample code that does most of the work for you). トークンの処理コードの詳細については、「プロバイダー向けのホスト型の低信頼 SharePoint アドインでセキュリティ トークンを処理する」を参照してください。For more information about token-handling code, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.

前提条件Prerequisites

SharePoint アドインでコンテキスト トークン フローを使用可能にするには、事前に次の予備的な手順を完了しておく必要があります。The following preliminary steps must be completed before a SharePoint Add-in can use the Context Token flow:

  • SharePoint アドインをオンプレミスの SharePoint ファームにインストールする場合、SharePoint Online にのみインストールする場合には適用されない、以下のセットアップ要件があります。If the SharePoint Add-in is to be installed to an on-premises SharePoint farm, these setup requirements don't apply if it is only installed to SharePoint Online:

  • アドインを SharePoint Online にインストールするか、オンプレミスの SharePoint ファームにインストールするかに関わらず、SharePoint アドインを ACS に登録する必要がありますRegardless of whether the add-in is installed to SharePoint Online or to an on-premises SharePoint farm, the SharePoint Add-in must be registered with ACS. これを実行する方法の詳細については、「SharePoint アドインを登録する」を参照してください。登録の一環として、アドインは ACS にクライアント ID とクライアント シークレットなどを提供します。For details about how this can be done, see Register SharePoint Add-ins. Among other things, the add-in provides ACS with its client ID and client secret as part of the registration.

OAuth コンテキスト トークン フローの手順Context Token flow steps

次の図に、SharePoint プロバイダー向けのホスト型アドインの OAuth 認証と承認フローを示します。The OAuth authentication and authorization flow for a SharePoint provider-hosted add-in is shown in the following figure.

OAuth コンテキスト トークン フローOAuth Context Token flow

OAuth 認証処理フロー

図中の番号に対応する手順は次のとおりです。These are the steps that correspond to the numbers in the figure:

  1. ユーザーが SharePoint アドインを SharePoint から起動します。これが実行される方法は、アドインの設計によって決まります。A user launches the SharePoint Add-in from SharePoint. The design of the add-in determines how this is done:
  • アドインがアドイン パーツ (実質的には IFRAME を囲むラッパー) 内のリモート Web アプリケーション (Contoso.com にある) を表示するように設計されている場合、アドインの起動は、アドイン パーツの含まれる SharePoint ページに移動するだけで行えます。If the add-in is designed to surface the remote web application (at Contoso.com) in an add-in part (which is essentially a wrapper around an IFRAME), launching the add-in simply means navigating to a SharePoint page that contains the add-in part. (ユーザーがまだサインインしていない場合は、ユーザーがサインインするように SharePoint からメッセージが出ます。) SharePoint がページを処理し、ページ上に Contoso.com アプリケーションからのコンポーネントがあることを検出します。(If the user is not already signed in, SharePoint prompts the user to sign in.) SharePoint processes the page and detects that there is a component from the Contoso.com application on the page. (アドイン パーツの詳細については、「アドイン パーツを作成して SharePoint アドインと共にインストールする」を参照してください。)(For more information about add-in parts, see Create add-in parts to install with your SharePoint Add-in.)

  • アドインがブラウザー内のページ全体を使用するように設計されている場合、ユーザーがそのアドインを起動するには、SharePoint の Web サイトの [サイト コンテンツ] ページにあるアドイン タイルを選択します。If the add-in is designed to use as a full page in the browser, the user launches it by selecting its add-in tile on the SharePoint website's Site Contents page. (他のバリエーションとして、リモート コンポーネントを起動するカスタム メニューやリボン項目がアドインに組み込まれている場合があります。)(A variation of this is when the add-in includes a custom menu or ribbon item that launches the remote component.)

  1. アドインを起動する方法にかかわらず、SharePoint は Contoso.com アプリケーションに送信できるコンテキスト トークンを取得する必要があります。そのため、SharePoint コンテキストに関する情報 (現在のユーザー、リモート アプリケーション URL、その他) を格納するコンテキストトークンを作成するように ACS に依頼します。Regardless of how the add-in is launched, SharePoint must get a context token that it can send to the Contoso.com application, so it asks ACS to create a context token that contains information about the SharePoint context, including the current user, the remote application URL, and other information. コンテキスト トークンには、暗号化されたリフレッシュ トークンも含まれています。The context token also contains an encrypted refresh token.

  2. ACS は、Contoso.com のアドイン シークレットを使ったアルゴリズムを使用してコンテキスト トークンに署名し、それを SharePoint に返信します。ACS signs the context token by using an algorithm that uses the Contoso.com add-in secret, and returns it to SharePoint. ACS と Contoso.com アドインだけがシークレットを知っています。Only ACS and the Contoso.com add-in know the secret.

  3. Contoso.com アプリケーションがアドイン パーツに表示される場合、SharePoint は、アドイン パーツをホストするページをレンダリングし、アドイン パーツ内の IFRAME がコンテンツを取得するために呼び出す URL にコンテキスト トークンを追加します。If the Contoso.com application is surfaced in an add-in part, SharePoint renders the page that hosts the add-in part and adds the context token to the URL that the IFRAME in the add-in part calls to get its contents. Contoso.com アプリケーションがページ全体の場合、SharePoint はブラウザーを Constoso.com にリダイレクトし、リダイレクト応答の一部としてコンテキスト トークンを組み込みます。If the Contoso.com application is full page, SharePoint redirects the browser to Contoso.com and includes the context token as a part of the redirect response.

  4. コンテキスト トークンは、Contoso.com サーバーに送信されるブラウザー要求に組み込まれます。The context token is included in the browser request that is sent to the Contoso.com server.

  5. Contoso.com サーバーは、コンテキスト トークンを受け取り、署名を検証します (これを実行できるのは、クライアント シークレットを知っているからです)。The Contoso.com server gets the context token and validates the signature, which it can do because it knows the client secret. これにより、Contoso.com は、トークンが ACS によって発行されたものであり、SharePoint を詐称する第三者から発行されたものではないことを確認できます。This assures Contoso.com that the token was issued by ACS and not an imposter pretending to be SharePoint. Contoso.com は、コンテキスト トークンから更新トークンを抽出し、そのトークンをクライアント ID やクライアント シークレットなどの他の情報と一緒に ACS に送信して、SharePoint にアクセスするためのアクセス トークンを要求します。Contoso.com extracts the refresh token from the context token and sends it, along with other information, including its client ID and client secret, to ACS in a request for an access token that allows it to access SharePoint.

  6. ACS は、更新トークンを検証してトークンを発行したことを確認し、Contoso.com にアクセス トークンを返します。ACS validates the refresh token so that it is assured that it issued the token, and then it returns an access token to Contoso.com. 必要に応じて、Contoso.com は、このアクセス トークンをキャッシュすることができます。これにより、SharePoint にアクセスするたびに ACS にアクセス トークンを要求する必要がなくなります。Optionally, Contoso.com can cache this access token so it doesn't have to ask ACS for an access token every time that it accesses SharePoint. 既定では、アクセス トークンは一度に数時間は有効です。By default, access tokens are good for a few hours at a time. (この記事の執筆の時点では、ACS が SharePoint に発行するアクセス トークンの既定の有効期間は 12 時間ですが、これは変更される可能性があります。)(When this article was written, the default expiration for ACS-issued access tokens to SharePoint was 12 hours, but that could change.)

各アクセス トークンは、承認を求める最初の要求で指定されたユーザー アカウントに固有のもので、その要求で指定されたサービス (この場合は SharePoint) に対するアクセス許可のみを付与します。       Each access token is specific to the user account that is specified in the original request for authorization, and grants access only to the service (in this case, SharePoint) that is specified in that request. リフレッシュ トークンの有効期限はさらに長くなっており (この記事の執筆の時点では 6 か月)、これもキャッシュすることができます。Refresh tokens are longer lived (six months when this article was written) and can also be cached. したがって、リフレッシュ トークンそのものが期限切れになるまでは、同じリフレッシュ トークンを ACS からの新しいアクセス トークンに対して再利用できます。So, the same refresh token can be redeemed for a new access token from ACS until the refresh token itself expires. (トークンのキャッシュの詳細については、「プロバイダー向けのホスト型の低信頼 SharePoint アドインでセキュリティ トークンを処理する」を参照してください。)(For more information about caching tokens, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.)

リフレッシュ トークンが期限切れになると、Contoso.com は新しいコンテキスト トークンを取得することによって新しいリフレッシュ トークンを取得できます。When the refresh token expires, Contoso.com can get a new one by obtaining a new context token. 詳細については、「新しいコンテキスト トークンを取得する」を参照してください。For more information, see Get a new context token.

  1. Contoso.com は、アクセス トークンを使用して SharePoint REST API 呼び出しを行うか、spnv に CSOM 要求を出します。Contoso.com uses the access token to make a SharePoint REST API call or CSOM request to spnv. これは HTTP Authorization ヘッダーに入れて OAuth アクセス トークンを渡すことによって行われます。It does this by passing the OAuth access token in the HTTP Authorization header. (お使いのリモート コンポーネントが .NET プラットフォームでホストされている場合、ヘッダーを作成するサンプル コードが Office Developer Tools for Visual Studio に添付されています。)(Sample code for creating the header is provided in the Office Developer Tools for Visual Studio if your remote component is hosted on a .NET platform.)

  2. SharePoint は、アクセス トークンを検証し、トークンが ACS によって発行されたものであることを確認します。その後、Contoso.com から要求されたデータを Contoso.com に送信するか、Contoso.com から要求された作成、読み取り、更新、削除 (CRUD) 操作を実行します。SharePoint validates the access token so that it is assured the token was issued by ACS. It then sends the data that Contoso.com requested to Contoso.com or performs the create, read, update, or delete (CRUD) operation that Contoso.com requested.

  3. Contoso.com アプリケーションのページがブラウザー (または、アドイン パーツの IFRAME) 内でレンダリングされます。The Contoso.com application page renders in the browser (or in the IFRAME of the add-in part).

関連項目See also