SharePoint のアドイン承認ポリシーの種類

[アーティクル]
09/15/2021

この記事を読む前に、まず「SharePoint でのアドインアクセス許可」および「SharePoint アドインのコンテキストトークン OAuth フロー」の記事を読んで理解してください。

アドイン承認ポリシーの種類の概要

SharePoint では、3 種類の承認ポリシーを提供します。

アドイン用ポリシー。アドイン用ポリシーが使用されている場合、SharePoint はアドインプリンシパルのアクセス許可のみをチェックします。承認チェックは、現在のユーザー (もしある場合) のアクセス許可とは無関係に、現在のアドインが対象のアクションを実行するための十分なアクセス許可を持っている場合にのみ成功します。

経費承認アドインが、このポリシーを使用する設計になっているアドインの例になります。このアドインでは、通常は経費を承認できないユーザーが、特定の金額未満の経費なら承認することができます。例については、次のセクションのシナリオを参照してください。

注意

一部の API ではユーザーコンテキストが必要であり、アドイン用ポリシーでは実行できません。これらには、Project Server および Project Online とのやり取りや、検索クエリを実行するための多数の API が含まれます。
ユーザー用ポリシー。ユーザー用ポリシーが使用されている場合、SharePoint はユーザーのアクセス許可のみをチェックします。 SharePoint がこのポリシーを使用するのは、ユーザーがアドインを使用せずにリソースに直接アクセスしている場合です。たとえば、ユーザーが初めて SharePoint Web サイトのホームページを開いたり、PowerShell から SharePoint API にアクセスしたりする場合です。
ユーザー + アドインポリシー。ユーザー + アドインポリシーが使用されている場合、SharePoint はユーザーとアドインプリンシパルの両方のアクセス許可をチェックします。承認チェックは、現在のユーザーとアドインの両方が対象のアクションを実行するためアクセス許可を持っている場合にのみ成功します。

このポリシーが使われる例には、SharePoint 上のユーザーのリソースに SharePoint アドインがアクセスするケースがあります。この SharePoint アドインのリモートコンポーネント内のコードは、SharePoint に対してユーザー + アドイン用呼び出しを行うように設計する必要があります。

アドイン用ポリシーを使用するアドインのシナリオの例

Contoso の営業マネージャーである Adam が、アドイン用ポリシーを使用する経費申請アドインを購入するとします。アドインを購入する際、Adam にはダイアログが表示され、アドインにユーザーのアクセス許可の昇格を許可することを求められます。つまり、SharePoint に対するアドイン用呼び出しの実行をアドインに許可することが求められます。 Adam は要求されたアクセス許可をアドインに付与します。そして、彼は、Contoso の営業担当者全員分のアドインのライセンスを購入し、アドインを営業チームの SharePoint Web サイトにインストールします。

営業担当者は、その後すぐに新しい経費申請アドインを使用して、経費報告書を提出します。通常、営業担当者は自分自身の経費報告書を承認できません。しかし、Adam がアドインに許可を付与し、アドインが $50 未満の経費報告書を自動的に承認するように設定したため、営業担当者は、このアドインを使用して経費報告書を承認することができます。 $50 以上の経費報告書の場合は、アドインによって承認タスクが自動的に Adam に割り当てられます。

これは、承認された経費の SharePoint リストへの書き込みアクセス許可を SharePoint アドインに付与することで実装できます。しかし、ユーザーの中で、このリストに対する書き込みアクセス許可を持っているのは、人事管理マネージャーのみとなります。アドインのコードは、経費が $50 未満の場合は常に、SharePoint にアドイン用呼び出しを行って経費をリストに追加するよう設計されています。ユーザーのアクセス許可が確認されることはないため、ユーザーの $50 未満の申請は、そのユーザーがリストへの書き込みアクセス許可を持っていない場合でも、承認された経費リストに自動的に追加されます。

アドインが、アドイン用ポリシーを使用するためのアクセス許可を取得する方法

SharePoint に対してアドイン用呼び出しを行うには、アドインは、アドイン用ポリシーの使用許可を要求する必要があります。この要求は、アドインマニフェスト内で実行されます。これを行うには、次のマークアップに示すとおり、 AppPermissionRequests 要素に AllowAppOnlyPolicy 属性を追加し、その属性を true に設定します。

    <AppPermissionRequests AllowAppOnlyPolicy="true">
        ...
    </AppPermissionRequests>

注意

SharePoint アドインは、かつては "SharePoint 用アプリ" と呼ばれていました。下位互換性を維持するため、アプリのマニフェストスキーマは変更されませんでした。そのため、"app" という文字列が多くの要素名と属性名に現れています。

このアドインをインストールするユーザーには、この要求を承認するよう、ダイアログが表示されます。アドインがテナントのスコープでアクセス許可を要求する場合は、テナント管理者のみがアドイン用ポリシーの使用を許可できるため、そのアドインをインストールできるのはテナント管理者のみとなります。

アドインからのアクセス許可の要求のスコープがサイトコレクション以下であれば、サイトコレクション管理者がアドインをインストールできます。アクセス許可のスコープの詳細については、「SharePoint でのアドインのアクセス許可」を参照してください。

アドインがアドイン用呼び出しを行う方法

SharePoint に対するアドイン用呼び出しとユーザー + アドイン呼び出しの違いは、呼び出しに組み込まれるアクセストークンの種類の違いです。次のコードは、マネージコードの中でユーザー + アドイン用およびアドイン用のアクセストークンを取得する方法を示しています。詳細なコーディングは、Visual Studio のプロジェクトに Office Developer Tools for Visual Studio によって自動的に追加される TokenHelper.cs (または .vb) ファイルの中に記述されます。

    string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
    if (contextTokenString != null)
    {
        //Get context token.
        SharePointContextToken contextToken =
            TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
        Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);

        //Get user+add-in access token.
        string accessToken =
            TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;

        ClientContext clientContext =
            TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);

        //Do something. 
        ...
        
        //Get add-in-only access token.
        string addinOnlyAccessToken = 
                TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName, 
                                sharepointUrl.Authority, contextToken.Realm).AccessToken;
            //Do something.
            ...
    }

注意

OAuth 認証された呼び出しを行わないアドイン (たとえば、アドイン Web で動作する JavaScript のみのアドイン) では、アドイン用ポリシーを使用できません。これらのアドインでは、アクセス許可を要求することはできますが、そのためにはアドイン用 OAuth トークンを渡す必要があるため、アクセス許可を利用することはできません。 SharePoint の外部で動作する Web アプリケーションが含まれるアドインのみが、アドイン用トークンを作成して渡すことができます。

通常は、呼び出しを行うには、現在のユーザーが存在している必要があります。アドイン用ポリシーの場合、既存の SHAREPOINT\SYSTEM ユーザーに似た SHAREPOINT\APP が SharePoint によって作成されます。すべてのアドイン用の要求は SHAREPOINT\APP によって実行されます。ユーザーベースの認証で、SHAREPOINT\APP として認証することはできません。

アドイン用ポリシーを使用するためのガイドライン

アドイン用呼び出しは実質的にユーザーの特権を昇格するものであるため、アドイン用呼び出しを行うためのアクセス許可を要求するアドインを作成するかどうかは慎重に判断してください。呼び出しでアドイン用ポリシーを使用するのは、次の場合に限る必要があります。

特定の呼び出しについて、ユーザーのアクセス許可よりも高いアクセス許可までアドインを昇格する必要がある場合 (たとえば、アドインによって評価された条件で経費報告書を承認するため)。
アドインが特定のユーザーの代わりとして機能しない場合。たとえば、SharePoint ドキュメントライブラリの夜間保守作業を実行するアドイン。

次の方法で共有