分離された Web パーツ

  • [アーティクル]

この機能を使用すると、ページ上の他のコンポーネントやテナント内のスクリプトにも、アクセス トークンを公開せずに、Azure AD でセキュリティ保護された API と安全に通信する Web パーツをビルドすることができます。

分離された Web パーツを使用する理由

SharePoint Framework ソリューションが Azure AD でセキュリティ保護された API に安全にアクセスできるようにするために、API 管理を使用して、テナント内のスクリプトがどの API にアクセスでき、その際どのアクセス許可を使用するかを指定できます。 また、SharePoint Framework を使用して、特定の API のアクセス トークンを簡単に取得できます。 これにより、Azure AD でセキュリティ保護された API との通信が大幅に簡素化されるほか、特定の SharePoint Framework ソリューションだけでなく、すべてのスクリプトが、承認された API のアクセス トークンを取得できるようになります。 テナントで使用するスクリプトのいずれかが悪用された場合、現在のユーザーの代わりに、承認された API のいずれかにアクセスできます。

分離された Web パーツを使用すると、Azure AD でセキュリティ保護された API へのアクセスを分離し、特定の SharePoint Framework の Web パーツのみがその API のアクセス トークンを取得できるようにするための新しい方法を取り入れることができます。

分離された Web パーツの機能

重要

分離された Web パーツ機能は、SharePoint Framework v1.8 以降でのみ使用可能です。 分離された Web パーツは、モダン ページでのみサポートされます。 分離された Web パーツをクラシック ページに追加できる場合がありますが、発行時に Web パーツはレンダリングされず、エラーが生成されません。 分離された Web パーツは、テナント アプリ カタログにのみインストールできます。 サイト コレクション のアプリ カタログからは機能しません。

分離された Web パーツの機能を示すアーキテクチャの概要

分離された Web パーツ機能を使用するソリューションでは、 *.sppkg ファイルのプロジェクト メタデータに特定のフラグが設定されています。 アプリ カタログにこれらのソリューションを展開する場合、すべての API のアクセス許可要求は、分離されたものとして指定されます。

分離された API のアクセス許可要求が承認されると、Microsoft 365 のテナントにリンクされた Azure AD 内に、個別の Azure AD アプリケーションが作成されます。 この Azure AD アプリケーションは、API のアクセス許可を要求した SharePoint Framework ソリューションに固有のものであり、そのソリューションで要求された OAuth アクセス許可が設定されます。 OAuth 暗黙的フローによって使用される、その Azure AD アプリケーションの戻り先 URL は、その特定の SharePoint Framework アプリケーションに関連付けられている一意のドメインに設定されます。

分離されたアクセス許可を使用しているソリューションのすべての Web パーツは、ページに追加されると、その SharePoint Framework ソリューションに関連付けられている一意のドメインを指す IFrame を使用して表示されます。 この方法により、SharePoint Framework で一意の API のアクセス許可を実行でき、テナント内の他のソリューションやスクリプトがこれらの API へのアクセス トークンを取得できなくなります。

分離されたアクセス許可を使用するプロジェクトのスキャフォールディング

SharePoint Online を対象とする新しい SharePoint Framework プロジェクトをスキャフォールディングすると、SharePoint Framework Yeoman ジェネレーターに次のプロンプトが表示されます。

ソリューションのコンポーネントには、テナント内の他のコンポーネントと共有されていない一意の Web API にアクセスするためのアクセス許可が必要ですか?:

答えがはいである場合、ジェネレーターにより、isDomainIsolated プロパティが true に設定されて、config/package-solution.json ファイルのプロジェクトの構成にフラグが追加されます。 分離された Web パーツ機能は Web パーツにのみ適用されるため、ジェネレーターでは、プロジェクト内の Web パーツの作成のみが許可されます。

重要

理論上は、分離されたアクセス許可を使用するプロジェクトの SharePoint Framework 拡張機能を手動で作成することができます。 ただし、これは得策とは言えないため、決して実行しないでください。サポートもされていません。

追加した拡張機能が、Azure AD でセキュリティ保護された API と通信した場合、独立した方法でアクセス トークンを取得できなくなり、実行時に失敗します。

API との通信

分離されたアクセス許可を Web パーツで使用する点を除けば、Azure AD でセキュリティ保護された API へのアクセス トークンを取得するうえで、コード内で特別なことをする必要はありません。 さらに、実行時に分離された Web パーツが一意のドメインを指す IFrame 内で読み込まれるとしても、分離されていない Web パーツの場合と同じ方法で SharePoint REST API と通信できます。

分離された Web パーツを含むソリューションの展開

分離された Web パーツを含むソリューションは、通常の SharePoint Framework のソリューションと同じ方法で展開されます。 唯一の違いは、API のアクセス許可要求が分離されたものとして展開されることです。 これは API の管理ページで明確に表示されており、API のアクセス許可要求は適用対象のソリューションごとにグループ化されています。

テナントレベルで与えられる API アクセス許可は、すべての SharePoint Framework ソリューションまたはテナントのスクリプトの一部で使用できます。 一方、分離されたアクセス許可は、それらを要求したソリューションでのみ使用できます。

分離された Web パーツの使用

分離された Web パーツは、ページに追加されると IFrame を使用して表示されます。 この IFrame は、Web パーツが配置されている SharePoint Framework ソリューションに割り当てられている一意のドメインを指します。 このドメインは、その SharePoint Framework ソリューションの分離されたアクセス許可をホストするために作成された Azure AD アプリケーションの戻り先 URL でも参照されます。 一意のドメインを使用することにより、その SharePoint Framework ソリューションの Web パーツのみが、分離された一連のアクセス許可のアクセス トークンを取得できるようになります。

分離された Web パーツのプロパティ ウィンドウ

分離された Web パーツのプロパティ ウィンドウは、同じ Web パーツの 追加 インスタンスを持つ別の iframe としてレンダリングされます。 開発者が注意する必要があるいくつかの詳細が表示されます。

  • 分離された Web パーツのライフサイクル イベント (render など) は、Web パーツ自体に対して 1 回、プロパティ ウィンドウに対して 1 回呼び出されます。
  • プロパティ ウィンドウの iframe サイズは、パネルのサイズに制限されます。 プロパティ ウィンドウでモーダルまたはワイド コントロールを使用する予定がある場合は、それを考慮してください。

分離された Web パーツの破棄

分離された Web パーツの onDispose メソッドは 呼び出されない場合があります。DOM からの iframe の削除により、iframe のドキュメントに関連付けられているソケット接続を含むすべてのリソースが自動的にクリーンアップされます。

分離されたアクセス許可を使用する既存のプロジェクトのアップグレード

既存の SharePoint Framework プロジェクトを v1.8.0 にアップグレードして、分離されたアクセス許可機能を使用するには、config/package-solution.json ファイルで、isDomainIsolated プロパティを true に設定します。 プロジェクトに Web パーツだけが含まれていることを確認する必要があります。

分離されたアクセス許可を使用するようプロジェクトを変更した後、プロジェクトを再展開する必要があります。 これにより、ソリューションに分離された新しい API アクセス許可要求が発行されます。これにはテナント管理者による承認が必要です。

分離されたアクセス許可を含むソリューションの削除

分離された API アクセス許可を承認する場合、SharePoint では、アクセス許可を要求した SharePoint Framework ソリューションに固有の専用 Azure AD アプリケーションが作成されます。 SharePoint Framework ソリューションが、アプリ カタログから削除されるとき、API アクセス許可と Azure AD アプリケーションは削除されません。