アプリケーションのアクセス許可を登録する

適用対象: Developer

SharePoint Embedded アプリがコンテナーを作成する前に、または消費するテナント内のコンテンツにアクセスする前に、コンテナーの種類のアプリケーションのアクセス許可を登録します。

コンテナー タイプ ID と所有アプリケーションを用意できるように、最初に コンテナー タイプを作成して構成します 。

登録が必要な理由

SharePoint Embedded アプリケーションは、コンテナーの種類がそのテナントに登録されるまで、そのテナント内のコンテナーと対話できません。

登録コントロール:

  • コンテナーの種類にアクセスできるアプリケーション ID。
  • 各アプリケーションが持つ委任されたアクセス許可。
  • 各アプリケーションが持つアプリのみのアクセス許可。
  • ゲスト アプリケーションが所有アプリケーションのコンテナーと対話できるかどうか。

登録が見つからないか不完全な場合、後の呼び出しがアクセス拒否エラーで失敗する可能性があります。

登録できるユーザーを理解する

コンテナー タイプの所有アプリケーションのみが、消費テナントで登録 API を呼び出すことができます。

所有するアプリケーションには、以下が必要です。

  • 消費しているテナントにインストールされているサービス プリンシパル。
  • 使用中のテナントで登録を実行するための管理の同意。
  • FileStorageContainerTypeReg.Selected Microsoft Graph アクセス許可 (ユーザー委任またはアプリのみ)。
  • Microsoft Graph リソースの有効なトークン。

注:

コンテナーの種類登録 API は、Microsoft Graph v1.0 で使用できます。

所有アプリケーションがユーザーの代わりに (委任された) 登録 API を呼び出す場合、そのユーザーには SharePoint 埋め込み管理者 または グローバル管理者 ロールが割り当てられている必要があります。 ユーザー コンテキストなし (アプリのみ) で呼び出す場合は、クライアント資格情報の付与フローが使用されます。

消費中のテナント管理者に、所有しているアプリケーションに管理者の同意を付与するよう依頼します。

Microsoft ID プラットフォーム管理者の同意エンドポイントを使用します。

https://login.microsoftonline.com/{consuming-tenant-id}/v2.0/adminconsent?client_id={owning-app-clientid}&scope=https://graph.microsoft.com/.default&redirect_uri={spe-app-redirect-uri}

オンボード フローの成功とエラー処理を構成します。

国内クラウドのエンドポイントについては、「国内クラウドの Microsoft ID プラットフォーム エンドポイント」を参照してください。

登録用のトークンを取得する

登録には、代理認証またはアプリのみの認証を使用します。

登録には以下が必要です。

  • FileStorageContainerTypeReg.Selected Microsoft Graph のアクセス許可。
  • アプリのみの呼び出しの場合、 クライアント資格情報によってフローが付与されます。
  • 代理呼び出しの場合は、SharePoint Embedded 管理者またはグローバル管理者ロールを持つサインイン ユーザー。

コンテナーの種類のアクセス許可の登録

消費テナントの登録エンドポイントを呼び出します。

PUT https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypeRegistrations/{containerTypeId}

{containerTypeId} は、開発者テナントで作成されたコンテナーの種類 ID です。

要求の本文で、コンテナーの種類に対するアプリケーションのアクセス許可の付与を指定します。

登録を作成、置換、または更新する

完全な登録を置き換える必要があるか、選択したプロパティを更新する必要があるかに基づいて、操作を選択します。

目標 Microsoft Graph 要求 動作
登録を作成または置き換える PUT /storage/fileStorage/containerTypeRegistrations/{containerTypeId} コンテナーの種類 ID を使用して登録を作成します。 登録が存在する場合、要求によって完全なペイロードが置き換えられます。
選択した登録プロパティを更新する PATCH /storage/fileStorage/containerTypeRegistrations/{registrationId} Updates Microsoft Graph v1.0 で指定されたプロパティのみを更新します。

PATCH操作では、オプティミスティック同時実行制御の登録etagを使用します。 現在の登録を読み取り、更新プログラムの本文にその etag プロパティを含めます。 別の要求が最初に登録を変更する場合は、最新の値を読み取り、上書きする代わりに更新プログラムを調整します。

登録の更新が反映されるまでに最大 1 時間かかる場合があります。

APIの詳細は、「 fileStorageContainerTypeRegistrationの作成 」および「 fileStorageContainerTypeRegistrationの更新」を参照してください。

所有するアプリにアクセス許可を付与する

共通の初回登録では、所有アプリに委任された呼び出しとアプリのみの呼び出しに対する完全なアクセス許可が付与されます。

{
  "applicationPermissionGrants": [
    {
      "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab",
      "delegatedPermissions": ["full"],
      "applicationPermissions": ["full"]
    }
  ]
}

サンプルのアプリ ID を所有するアプリケーション ID に置き換えます。

注意

実稼働には最小特権を使用します。 アプリケーションでコンテナーの種類の完全なアクセスが必要な場合にのみ、 full を付与します。

ゲスト アプリにアクセス許可を付与する

所有するアプリは、別のアプリケーションのアクセス許可を登録することもできます。

ゲスト アプリで、バックアップや処理など、定義されたワークロードが必要な場合は、このパターンを使用します。

{
  "applicationPermissionGrants": [
    {
      "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab",
      "delegatedPermissions": ["full"],
      "applicationPermissions": ["full"]
    },
    {
      "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6cd",
      "delegatedPermissions": ["read", "write"],
      "applicationPermissions": ["none"]
    }
  ]
}

両方のアプリ ID をアプリケーションに置き換えます。

アクセス許可の値

アクセス許可 使用
none アクセス許可を付与しません。
readContent この種類のコンテナー内のコンテンツを読み取ります。
writeContent この種類のコンテナーにコンテンツを書き込みます。
create この種類のコンテナーを作成します。
delete この種類のコンテナーを削除します。
read コンテナー メタデータを読み取ります。
write コンテナー メタデータを更新します。
enumeratePermissions コンテナーのメンバーとロールを列挙します。
addPermissions コンテナー メンバーを追加します。
updatePermissions 既存のメンバーシップを更新します。
deletePermissions 他のメンバーを削除する。
deleteOwnPermission 呼び出し元自身のメンバーシップを削除します。
managePermissions コンテナー ロールの割り当てを管理します。
manageContent この種類のコンテナーのコンテンツを管理します。
full すべてのアクセス許可を付与します。

注:

writeContent readContent なしでは付与できません。

登録の検証

登録が成功すると、応答本文で 201 Created および構成されたアクセス許可が返されます。

登録成功後:

  1. 応答に想定されるアプリ ID が含まれていることを確認します。
  2. 委任された配列とアプリ専用の配列が、意図した許可と一致することを確認します。
  3. SharePoint Embedded のアクセス許可を持つ Microsoft Graph トークンを取得します。
  4. 登録したアクセス許可に一致する、リスクの低い操作を試してください。
  5. 「 認証と承認の構成」に進みます。
現象 考えられる原因 アクション
401 Unauthorized トークンが見つからないか無効です 有効なアプリ専用トークンを要求します。
403 Forbidden アプリにアクセス許可がないか、アプリを所有していない FileStorageContainerTypeReg.Selected、同意、アプリ ID を確認します。
404 Not Found コンテナーの種類が存在しません ID とテナントを確認します。
Graph 呼び出しでアクセスが拒否されました 登録が見つからない、または不十分である 必要なアクセス許可で再登録します。
管理は非表示のアクセス許可を見つけることができません ポータルでは公開されません 管理者の同意 URL を使用します。

安全に再登録する

登録 API を呼び出すことができる回数に制限はありません。

前回成功した登録呼び出しによって、消費しているテナントで使用される設定が決まります。

安全な更新プロセスを使用します:

  1. 変更の際に完全な PUT 交換が必要か、対象を絞った PATCH 更新が必要かを決定します。
  2. PUTの場合は、完全な登録ペイロードを作成します。
  3. PATCHについては、現在の登録etagを読み上げて含めます。
  4. アクセスを保持する必要があるすべてのアプリを含めます。
  5. 登録呼び出しを送信します。
  6. 応答を検証します。
  7. 各アプリ ロールに対してスモーク テストを実行する。

重要

結果の登録にそのアプリケーションとアクセス許可のセットのみを含める場合を除き、部分的なペイロードを送信しないでください。

次の手順

でトークンと承認フローを構成する 認証 と承認の構成.